Have you ever created a set of actions over and over again because the same situation keeps coming up?
For example, let's say you have a complicated commission formula which takes about six actions to calculate. In order to use this formula, you start repeating the same six actions in different controls.
App Routines allows you to take a set of actions and define it as a routine. And then you can call that routine within your app, and Method would run the actions defined in the routine.
This allows you to reuse a set of actions over and over again without having to copy the same code.
Furthermore, App Routines also allows you to give it information, and depending on the information you give it, it will return a value.
Let's show this by example. In our scenario, there is a form we want our customers to fill out. When we receive their input, we want to convert it to uppercase, as well as remove any blank spaces.
The first thing we need to do is define the app routine.
Where to Create App Routines
App Routines are defined per app. In other words, an app routine is only visible within the app it is defined. Although other apps will not be able to use it, any screen inside the app is able to use the app routine.
To create an app routine, you need to manage the app. In this scenario, we will use an app called Contact Form.
1. Click the vertical ellipsis ( ⋮ ) and select manage in the app you wish to define the app routine.
2. Select App Routines on the left menu.
3. To create a new app routine, select the New Routine button.
4. Give the app routine a name and description.
Once saved, you will be presented with a page to define the App Routine.
How to Define an App Routine
There are four sections you need to be aware of when defining an app routine:
- General: By clicking the edit button, you can edit the routine's name and description, as well set the routine as active or inactive.
- Inputs: An app routine can have multiple inputs stored in separate action results. These action results will be available when defining actions in the next section. In this section you define the action results and the type of data you expect to be inputted.
- Actions: This is where you create the set of actions which are part of this app routine.
- Outputs: An app routine can return multiple action results.
Note that the Actions section says "Edit Draft Actions". This is because App Routines are not available to be used until they are published. Until then, they are in a draft state.
Continuing with our scenario, let's define our this app routine.
Scenario Part 1 - Define Input and Outputs.
Our app routine will expect one input: the text we need to convert. It will also return one ouput: the text after the conversion. We will create one action result for the input (arInput1), and another action result for the output (arOutput1).
Scenario Part 2 - Define the Actions
When you click Edit Draft Actions, you will be taken to the action editor which is exactly the same as editing actions on an app screen, except this time, the header is coloured blue.
Explaining how actions work is beyond the scope of this article, so here's a quick overview on the actions being put into this app routine.
The first action will convert whatever was stored in arInput1 to uppercase and then it will store the result back in the same action result. Note that the arInput1 action result was first defined in the app routine as an input.
The second action will remove spaces which are in arInput1. The results are stored in the output action result arOutput1.
With this, our example app routine is done! You can save this action set, and then save the app routine as well.
Test and Publish the App Routine
Remember, an app routine isn't available to use until it is published, so even if you save it, it's still unavailable to use. Once you've saved your app routine, you can now test it.
At the bottom of your app routine screen, you will find a More Actions button with four options:
- Test App Routine: Go to a separage page where you can see if your app routine works.
- Copy App Routine: Create a copy of your app routine. If the app routine is published, the new copy will be in draft.
- Publish Draft: If the current app routine is in draft, you can publish it to be available to use.
- See All Revisions: Once an app routine is published, it cannot be edited. You can, however, create a second draft (different from a copy), that will show up under revisions. This will be further covered below.
Let's test the app routine in our scenario. First, select the revision you wish to test. After that, you place the input you want the App Routine to process. When you click the Test App Routine button, you will see the output.
In our example app routine, you can see from above it works perfectly! We can now go back and click the Publish Draft option and the app routine screen changes to reflect it's published state.
Note that by editing either the input or the output, you will create a new copy of your app revision. This copy will not show up under "All Revisions", because you cannot change the number of input or outputs once you publish an app routine.
Use your App Routine in your App
Once your App Routine is created, you can use it when customizing a screen with the Call Routine action.
In our example, the Call Routine action is set up as shown:
- Select a Routine: Choose an active app routine defined in the app. For app routines with multiple revisions, the published reversion will be selected.
Input Action Results: All the input action results will be shown.
Note: This CANNOT be populated by an on-screen control. If you wish to populate this input from a control, you must first put the control's value into an action result.
- Output Action Results: All the output action results will be shown here where you can assign it to another action result or a control on screen.
Creating a New App Routine Revision
Once your app routine is published, you will have the option to create a new draft from the More Actions button:
When you select the Create Draft option, you will be immediately taken to your new draft where you have the option to Edit draft Actions:
You can also preview the published actions of the live version from here as well. Remember, you cannot change the inputs or the outputs when creating a new revision of an app routine. You will need to create a new copy of the app routine if you wish to change the inputs / outputs.
Once you have finished modifying the actions for this new revision, the More Actions button has one more option to choose:
This allows you to delete the draft you just created. By the way, you cannot delete an app routine. You can only set it to inactive by selecting the edit button.
You can also publish and delete a draft by in the Revisions page when you See All Revisions:
Once you publish your new draft, the previous revision will be set to an archived status. If you were to make more drafts and publish them, you will be able to switch between any archived version.