Change Control

Overview 

By default, whenever you update a story in Tines, your changes immediately take effect. This works well for simpler use cases and especially for building out v1 of your workflow.

For up-and-running, mission-critical workflows, however, it's important to have greater oversight of changes. You need to be able to safely experiment with ideas for improvements and apply a complicated change-set in one fell swoop. That’s where Change Control comes in.

💡Note

Enabling change control 

For any story, you can enable Change Control by using the Switch located at top right of the storyboard.

Once enabled, your story is considered LIVE and read-only. No changes can be made to the story without first going through a review and approval process.

Tenant owners can specify that all stories created within a team or within a tenant have change control turned on by default. Only Team admins and users with the custom permission change control: manage can toggle change control off on a story. See Change Control Settings for further details.

Using change control 

Once change control is enabled on a story, a user will follow the below steps to update that story.

Create a draft 

A draft is an editable copy of your live story. Users can freely make changes and test those changes within their draft without impacting the live, running story.

To create a draft, select the arrow next to your story name in the top header and click + Create new draft. You can also view and select any existing drafts previously created by you or other users in your team. Drafts are collaborative, meaning multiple users can view and make changes in one draft. Additionally, users can create multiple drafts.

Build and test your changes 

You can build inside a draft as you normally would in Tines.

Send external data to a specific draft 

While building and testing your changes in Tines, you may want to send external data to your draft rather than to the live story. To do this, send your data to the unique URLs associated with your story's webhook, page, or receive email action.

  • Webhooks: webhook URLs in drafts include a parameter ?draft=mydraftname. Easily locate and copy this URL by locating the webhook action in your draft and copying the Webhook URL section on the right hand action configuration panel.

  • Pages: page URLs in drafts include a parameter ?draft=mydraftname. Easily locate and copy this URL by locating the page in your draft and selecting Copy link from the toolbar below the page.

  • Receive email: receive email actions in Mode:Email will have a unique email address per draft. Easily locate and copy this URL by locating the receive email action in your draft and copying the Email address section on the right hand action configuration panel.

  • Send to story: this action sends data to a sub-story in Tines. If you would like to send data to a specific draft of a sub-story, configure the optional parameter Send to draft specifying the draft ID. Easily identify the draft ID with the key SEND_TO_STORY.

Use Live events in a draft 

While you can send external data to a specified draft (as noted in the above section), you may also want to test using data from your live story. By default, live events are included on the events list in drafts. You can enable / disable live events by using the toggle in the events panel.

In addition to viewing live events in the action events list, you can also

  1. Use live events to test an action in a draft

  2. Re-emit a live event into a draft

  3. Use live events in auto-complete suggestion in the action builder

Use different resources and credentials in a draft 

Depending on your workflow development style, you may want to target independent test versions of some or all external services.

You can achieve this by enabling and configuring test values for your credentials. Tines will automatically use the test credential value when running in a draft environment and seamlessly switch to the live credential value when running in the live environment.

Alternatively, you can also configure a different credential or resource by using our META.story.is_draft variable, and an IF function inside your action configuration. For example, to target your development Jira instance in Test, and your production instance in Live, you could use an expression like:

IF(META.story.is_draft, CREDENTIAL.jira_test, CREDENTIAL.jira)

Request a review 

Once you have built and tested your changes, request a review of those changes before they update the live story. To do this, select View changes in the upper right of the storyboard. This will generate a modal visualizing your changes on a per-action basis. Within this modal, you can:

  • Review your changes made

  • Add a name for your change request

  • Add further details in the description of your change request

Select the button Request review once your request is appropriately filled out.

❗️Important

Review changes 

Once a review is requested, a notification is sent within the Tines UI and to the change control webhook, if configured. Changes requests can only be approved by a Team Admin or a user with the custom permissions change control: review or change control: manage.

To review the changes, navigate to the draft and select View request. This will generate a modal visualizing the requested changes on a per-action basis along with the context of the request name and description.

Within this modal, you can toggle the following settings that are on by default:

  • Show storyboard: shows a visual of the action in the storyboard that has been changed

  • Hide positional changes: hides any changes to action positions as these changes are purely visual and cannot break a story's functionality

Once you have reviewed the changes, reject, approve, or cancel the request. Similar to when the review was requested, a notification will be sent within the Tines UI and the change control webhook, if configured, once one of the review actions is selected.

Push changes 

If the change request is approved, the changes can be pushed to the live story. Navigate to the draft and select View request. Select Push to update the live story with your changes. After pushing, your changes will be applied together in a single update.

Any in-flight story runs will immediately switch over to the new logic, consistent with how edits to non change-controlled stories are applied. The draft will be deleted as the changes are now applied in the live story.

View previous changes 

Within the live story, you can see previous change requests, as well as their attached descriptions, via story versions.

Change control notifications 

Change control notifications are managed using webhooks at the team level. A webhook event will be generated if the story change request is created, cancelled, approved, rejected or pushed.

You can configure a webhook notification endpoint by selecting your team in the top left navigation menu, manage team, notifications. Then input a webhook URL under the Change control heading.

At the tenant level, audit logs capture all change control related operations as well.

🪄Tip

Change control settings 

Tenant owners can configure the following settings related to change control. Navigate to this section by selecting the left hand menu, and clicking Settings. Within the settings center, select Change control under the Configurations sub-menu.

  • Enable change control for all teams: change control is automatically turned on when a story is created throughout the tenant.

  • Enable change control for selected teams: change control is automatically turned on when a story is created within the specified teams.

  • Require approval for all changes: this requires the user approving the change to be different than the user who requested the change. Users with Team Admin permissions can bypass this requirement for emergency circumstances. If bypassed, a notification is sent to the change control webhook. NOTE: users with custom permissions change control: manage or change control: review do not have the ability to bypass changes.

  • Require name and description for all change requests: a change cannot be requested for review if the name or description field is blank.

Limitations 

Drafts are only active and capable of receiving webhook events while being worked on by users within Tines. After a period of inactivity, any webhook in a draft will no longer process requests.

API endpoints 

Some API endpoints have parameters that are related to drafts.

If an endpoint has a draft_id parameter, passing a draft ID (which can be found after /drafts/ in the story's URL) means that the request will be applied to that draft.

Some endpoints also have a mode or story_mode parameter. These exist for backwards compatibility. If mode or story_mode is LIVE the request will be applied to the live story. If mode or story_mode is TEST then the request will be applied to a draft called test if such a draft exists. If draft_id is present, mode or story_mode will be ignored.

Was this helpful?