Change Log

Improvement

• replaced customizations with models in examples
• clean up output of form variable when custom_image/custom_attachment is provided

New Feature

• allow user to access their custom request headers via context.headers

Bug Fix

• filtering data by empty values - users and models endpoints will properly filter items with values that are empty. For example:
• `models(
• per_page: 20,
• filter: {
• properties: [{ name: "warning", value: "" }]
• }
• ) { ... }
• `
• removed articles about CustomAddress - there is a better way now via models - [https://documentation.platformos.com/developer-guide/records/using-geojson-format-geolocation]
• exception in data import is no longer raised when item with given external id does not exist
• 500 error when trying to include partial without a name - {% include '' %} will render user friendly error
• gracefully handle exception in jwt_decode filter
• gracefully handle empty string provided to parse_json filter/tag

Improvement

• admin_ GraphQL mutations - modules/my_module_name prefix will be automatically added to the name of notifications, authorization policies, etc., based on physical path, to make it consistent with the pos-cli behavior
• layout validation - added validation to the layout property of Page to make it impossible to assign layout which does not exist
• validate Model belongs to the defined Model Schema - when defining a Form with a concrete Model Schema name as resource, it will not be possible to use it to update the Model, which belongs to the different Model Schema
• form and data in the notifications - previously data was accessible if the Notification was triggered via GraphQL and form if it was triggered via Form. Now you can always use both, which should make it easier to re-use Notifications. Also, documentation for triggering an API Call Notifcation was updated accordingly to show both ways of triggering it.
• validation for related resources in GraphQL - GraphQL will return an error if you try to use invalid values (for example property name which does not exist) for related models.
• pos-cli changelog is [kept separately].

New Feature

• graphql models() can be filtered by related users: for example you can filter cars by owner name
• ` models(
• per_page: 10
• filter: {
• name: { value: "cars" }
• related_users: { join: { foreign_property: "car_id" }
• filter: { properties: [{ name: "name" value: "Mike" }]
• }
• }
• }
• ) { ... }
• `
• multilingual notifications - added locale attribute to Email/SMS/API Notifications, which accepts liquid, to evaluate to the locale which should be used for translations
• auth0 integration - added auth0 integration and documentation on how to integrate various Identity Providers (Auth0, Facebook, Twitter etc.) with platformOS

Improvement

• Last edit:
• page slug can now consist of any components: Previously the page slug had to be maximum three levels deep. The improvement allows you to provide any slug you want, for example /one/two/three/four/five. However, please note that if you define page /one/two/three/four you won't be able to access /one/two/three/four/five - template slugs still work only for three-level deep slugs.
• {{ form }} output improved: The form variable will not include magical keys anymore, the output now corresponds to the fields defined in form configuration.
• {{ hash }} and {{ array }} will render proper JSON: You don't need to use the json filter. {{ users | json }} will become {{ users }}. The change is backward compatible, meaning the extra | json is just unnecessary but does not break anything.
• added filter by searchable field to admin_pages graphql endpoint: With a new filter you can exclude some pages from being shown in search results.

Improvement

• pos-cli: the gui serve will return a user friendly message if the port is already taken.
• pos-cli: the audit command will be automatically run during deploy; its performance has been greatly improved.
• Redesigned emails for modules in Partner Portal
• Renamed Customization to Model and CustomModelType to Model Schema - all existing occurrences of deprecated namings were removed from examples, documentation and platform.

New Feature

• pos-cli: the old marketplace-kit has been forked into a new package - [pos-cli] ([on github]). From now on marketplace-kit is in archive mode and will no longer be developed.
• Follow these steps to migrate from marketplace-kit to pos-cli:
• When using local node installation (for example installed using nvm or brew):
• `npm r -g @platform-os/marketplace-kit
• npm i -g @platformos/pos-cli
• `
• When using global node installation (use sudo if the version without it does not work):
• `sudo npm r -g @platform-os/marketplace-kit
• sudo npm i -g @platformos/pos-cli
• `
• From now on, use the pos-cli command instead of the marketplace-kit command, and remember to update your scripts if they used marketplace-kit.
• form_submit mutation was added to GraphQL: This new mutation will trigger a form submission along with invoking authorization policies and validation. It accepts two parameters: form_name and params. This way, you will be able to easily validate any user parameters against a given form configuration and persist it if valid. Most useful for creating API endpoints which re-use existing form configurations.
• Added the possibility to fetch related users for the models GraphQL query - [Model]

Bug Fix

• Fixed a couple of issues related to ElasticSearch type collision removal - mainly for related models
• Removed MIT license hardcoded text in Partner Portal

Improvement

• form_name optional: No need to duplicate GraphQL mutation input via Form - the form_name attribute is now optional in GraphQL mutations like user_create, user_update, customization_update, etc. You can still use it if you want to leverage existing configuration doing something in a callback/async callback or for sending emails, but you don’t have to.
• Set http_status to Authorization Policy: Added possibility to set http_status to Authorization Policy (previously hardcoded to 403). This allows you to render your custom 404 when an Auth Policy is violated. Moreover, now you can also customize 403, 500, and 503 (maintenance) pages by creating a page with the corresponding slug - 403, 500, or 503.

Bug Fix

• Double error message: Fixed double error message for image validation (that occurred in some cases).

Improvement

• Protected context.constants: context.constants are now properly protected from accidental leaking. They won’t be visible when you do {{ context }}, you have to explicitly call {{ context.constants }}. Soon, we will add a UI to add/remove them via the Partner Portal.

New Feature

• Added context.device key: It includes information about device type, like desktop, smartphone, etc. Should save you some work.
• Search by ID for admin_* queries: Added the possibility to search by ID for admin_* queries. Also, added metadata to all admin_* resources (possible to set them via GraphQL).
• User session timeout: You can now change the duration of a user session to control when the user timeouts.
• Developer guide icon
• Follow our step-by-step tutorial to learn more about [Updating Instance Configuration and setting the duration of a user session].

Improvement

• Bulk update all data: We have pushed some data import/export improvements. Now, you should be able to use data import to actually bulk update all data, not only the ones which were imported initially.
• Deleting line in yml file: Deleting line in a yml file will work as expected - as if it never has been there, instead of pretending it was not deleted. This bug forced you to explicitly set the property to a blank string instead of just removing it, like for callback_actions in Form, etc. It will be applied only to new Instances, because we did not want to risk breaking your Instances with the next deploy if for some reason you unknowingly relied on this bug. We will add a flag to the Partner Portal soon which would allow you to leverage the bug fix in a controlled way for existing Instances.

New Feature

• Properties for all users: You can now set properties directly in the user object, no need to go through the user profile. You can define properties all users should have via the app/user.yml file.
• Developer guide icon
• Follow our step-by-step tutorial to learn more about [Creating a Property for All Users].
• Liquid in page metadata: Page metadata now accepts Liquid and it will evaluate it for each page render. Same for layout.
• Migration invoked during module installation: Migrations added to the module will now be invoked during module installation, no need to do the full deploy.

Improvement

• Using parse_json filter while keeping your json tidy and formatted forced you to use capture.
• parse_json tag is basically a hybrid of capture and to_hash, it parses json string inside of the tag and converts it to a hash.
• Why would you want to convert your json config to a hash?
• To be able to iterate over it, use filters that will modify the structure, traverse the tree.
• `
• {% parse_json car %}
• {
• "maker": "Honda",
• "model": "CRX",
• "version": "EE8",
• "power": 180
• }
• {% endparse_json %}
• Hash: {{ car }}
• JSON: {{ car | json }}
• Properties:
• {% for property in car -%}
• {{ property[0] }}: {{ property[1] }}
• {% endfor %}
• `
• Result:
• `Hash: {"maker":"Honda","model":"CRX","version":"EE8","power":180}
• JSON: {"maker":"Honda","model":"CRX","version":"EE8","power":180}
• Properties:
• maker: Honda
• model: CRX
• version: EE8
• power: 180
• `
• Usage of parse_json is exactly the same, as a matter of fact, to keep backwards compatibility, to_hash still works.
• `
• {% assign car = '{ "maker": "Honda", "model": "CRX", "version": "EE8", "power": 180 }' %}
• {% assign object = car | parse_json %}
• Maker: {{ car.maker }}
• `
• Result:
• `Maker: Honda
• `

New Feature

• To make your work with json easier we introduced parse_json tag and renamed to_hash filter to parse_json.

Improvement

• Last edit:
• In this release we are answering to community requests and introducing two ways to benchmark performance of your code.
• This filter can be used in many different ways, including:
• calculating how many days from now will an event happen - just pass two dates and unit d for days
• calculating when you have to leave to arrive at train station - just pass two time objects and unit m for minutes
• calculating precisely how long something took - for example, code execution, pass two time objects and unit ms for milliseconds (default)
• You can use time_diff anywhere where liquid is allowed, for example: partials, callbacks.
• You can also measure how long graphql query is taking by putting it between start/stop variables you are measuring.
• To measure speed of code snippet:
• `
• {% assign start = "now" | to_time %}
• {% assign letters = "A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z" | split: "," %}
• {% for letter in letters %}
• • {{ letter }}
• {% endfor %}
• {% assign stop = "now" | to_time %}
• {% assign durationInMS = start | time_diff: stop %}
• {% assign durationInS = start | time_diff: stop, 's' %}
• {% log durationInMS, type: 'render alphabet in a list in milliseconds' %}
• {% log durationInS, type: 'render alphabet in a list in seconds' %}
• `
• Using pos-cli logs command observe what has been logged:
• `[2018-11-15 16:23:33.719Z] - render alphabet in a list in milliseconds: 7.392
• [2018-11-15 16:23:33.741Z] - render alphabet in a list in seconds: 0.007
• `
• [Read more about time_diff filter].
• You can now profile your application per liquid view (including partials) by setting up a enable_profiler: true flag inside your page.

• app/views/pages/my-slow-page.liquid

• `---
• enable_profiler: true

• `
• When the flag is set, whenever you trigger a request to the my-slow-page, two log entries will be added and accessible via the pos-cli logs command.
• The first one shows information about the page, the second one about the layout associated with the page.
• You can use this information to identify slow code and improve it.
• Note
• To avoid noise, the log will include only entries which took longer than 10ms
• `[2018-11-15 17:39:48.733Z] - debug: PROFILING:
• [0.015517108] TOTAL (lvl: 0)
• [0.013081715] if url_params (lvl: 1)
• [0.013057744] include 'designers/all_designers' (lvl: 2)
• [2018-11-15 17:39:48.816Z] - debug: PROFILING:
• [0.067086901] TOTAL (lvl: 0)
• [0.056122558] include 'layouts/header' (lvl: 1)
• [0.055988452] include 'layouts/theme_header' (lvl: 2)
• [0.055747433] if current_user == blank (lvl: 3)
• [0.055718548] include 'layouts/theme_header/signed-in-nav' (lvl: 4)
• [0.050209644] query_graph 'get_unconfirmed_orders_count', result_name: 'g__unconfirmed', receiver_id: context.current_user.id (lvl: 5)
• `
• Warning
• Try to not profile a page on production, as it can result in performance hit. If you absolutely have to, make sure to disable it right after you trigger the request to the page, to minimize the risk of leaving profiling enabled for a long period of time.

Improvement

• Some users reported issues with running very long tasks in async_callback_actions because the task was too slow to execute.
• Before, you had no control or information about limits, errors, timeouts.
• You have full control over priority of your async_callback_actions.
• If you don't set priority at all, it will be set to default.
• You can also set maximum number of attempts if job fails for whatever reason - timeout, error in the code, 3rd party api not responding
• Default is 1. Use it with caution, as every attempt uses resources.
• `
• [...]
• async_callback_actions:
• delay: 10
• priority: low
• max_attempts: 2
• content: >
• {% graphql res = 'long_running_task' %}
• [...]
• `
• Priority
• Timeout
• high
• 1 minute
• default
• 5 minutes
• low
• 4 hours
• Keep them in mind when writing code so that it runs fast enough for its priority.
• Additionally, when a job fails or timeouts it will be logged so you will know when something goes wrong.
• You can access the log using pos-cli logs command.