It's quite common to want to run a workflow multiple times with different inputs. A use-case for this might be deprovisioning a large list of users where there's no easy logic you can define in a filter, or perhaps onboarding some contractors who aren't in your HR system.
One solution to this is to use an API webhook trigger, and a small Powershell or zsh script that we've provided for you.
First of all we're going to create the workflow using the API webhook trigger:
If you already have a workflow that uses a different trigger you can convert it to the API webhook type:
Stepping back a bit, our starting point is going to be some data in a CSV file, e.g.
email,reason
erika.mustermann@example.com,Change of role
jane.doe@example.com,Inactivity
We're going to use a script to turn that CSV into JSON which will get sent to Trelica.
The structure is going to be an array of items, where each item in the array is going to use the CSV file column name, i.e.
{
"items":
[
{
"email": "erika.mustermann@example.com",
"reason": "Change of role"
},
{
"email": "jane.doe@trelica.com",
"reason": "Inactivity"
}
]
}
When we configure the webhook we need to be thinking about the JSON that is going to be sent to it.
- Check Multiple entries in one request because we're going to be passing an array.
- Enter
items
for JSON path to array as this is the JSON attribute that contains the array. - Pick the workflow context. In this case we want to identify users by email for a specific application so we've selected User for the context and selected 'Front' as the Application from the dropdown.
- The Type dropdown is how we're going to look up the person - in this case by Email although you could do this by the ID of the person in the application. The JSON path is
email
since that's the name of the column in the CSV (and our script will take the column names and use them for the JSON attributes). - Finally we're going to add an input field for the
reason
column. This is some text we're going to include in a Slack message in this example. Click the Add field dropdown and choose Add new field... - You can just enter the name ('reason') and this will automatically set the id (which is used to identify the input field in the JSON. More advanced JSON logic can be specified in the Advanced options but you shouldn't need to use this.
- Click Create, and then back in the workflow click Save draft and then Test webhook:
- Copy the URL to the clipboard and then switch to a terminal or command window.
- Download the
Run-Workflow.ps1
Powershell file from https://github.com/trelica/powershell/blob/main/Run-Workflow.ps1 and save it to a folder.
There's a zsh equivalent in the same location calledrunworkflow.sh
. The CSV parsing in Powershell is significantly better. -
Powershell
From a terminal or command prompt window run Powershell (
pwsh
) and enter the command below, altering to point to the correct path for your CSV file, and using the URL you just copied to the clipboard. The XXXXX for the secret is intentional - we'll set this shortly../Run-Workflow -CsvFilePath ~/tmp/example.csv `
zsh
-Secret XXXXX `
-Url https://app.trelica.com/FlowApi/webhook-test/66bf06dda668a6355bb8d1a3/XXXXXXXXXXXXXXXXXXXXXXIf you're using the zsh version you can try the
runworkflow.sh
script. Don't forget to set execute permissions before running (e.g.chmod +x ./runworkflow.sh
)./runworkflow.sh -f ~/tmp/example.csv -s XXXXX \ -u https://app.trelica.com/FlowApi/webhook-test/66bf06dda668a6355bb8d1a3/XXXXXXXXXXXXXXXXXXXXXX
-
The output should be similar to this:
POST: { "items": [ { "email": "erika.mustermann@example.com", "reason": "Change of role" }, { "email": "jane.doe@example.com", "reason": "Inactivity" } ] } workflowRunId workflowRunLink success ------------- --------------- ------- 000000000000000000000000 https://app.trelica.com/Admin/FlowItem/000000000000000000000000 True
- Have a look at the Test webhook dialog. Only one entry is shown because we're matching to multiple entries. Notice how the JSON has been mapped to context and the 'reason' field we added:
- Now that we've tested things, Close the dialog and we can prepare to run this for real.
Let's add another step to actually deprovision an account. Since this is normal workflow you can do lots of other things such as conditional actions or sending messages via Slack. Notice how we're using the 'reason' field as a mail-merge field in the Slack message:
- The final step is to make things more secure by passing a shared secret. On the API webhook trigger step, click Verify request, and enter
x-secret
as the Header name. - Finally, click the pencil icon to set the Header value. Click Generate, copy the secret to the clipboard, and click Use secret.
- To run this live, we need to Save draft, Enable the workflow, and take a copy of the live URL to use in our command.
Put the secret and the live URL into the command:
Powershell
./Run-Workflow -CsvFilePath ~/tmp/example.csv `
-Secret 4799xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ED0 `
-Url https://app.trelica.com/FlowApi/webhooks/66bf06dda668a6355bb8d1a3/xxxxxxxxxxxxxxxxxzsh
./runworkflow.sh -f ~/tmp/example.csv \ -s 4799xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ED0 \ -u https://app.trelica.com/FlowApi/webhooks/66bf06dda668a6355bb8d1a3/xxxxxxxxxxxxxxxxx
The live URL is different to the test URL. If the workflow is not enabled then the web-request will fail with an HTTP 404.The response should now show a workflow run ID and link:
Response: { "workflowRunId": "66bf68cea668a6355bb8ebd3", "workflowRunLink": "https://app.trelica.com/Admin/FlowItem/66bf68cea668a6355bb8ebd3", "success": true }
- If you now go to the Workflow run list, you should see two successful workflow runs:
- Click to view the details or investigate any issues.
- An alternative approach to running the workflow would be to paste JSON directly into the Trelica UI by using Run now:
Choose Paste JSON and click Run now:
Comments
0 comments
Please sign in to leave a comment.