Documentation › Service Hooks
Start a process from another tool: service hooks
A hook is an address that another tool calls when something happens: a work item or an issue is created, a message is posted in Teams, an email arrives… SerenForce then finds the right process and automatically starts a process instance, with the title of the item in a variable if you wish. Five tools are supported: Azure DevOps, Jira, Microsoft Teams, Outlook email and Custom (any tool that can send data to an address).
What is a hook for?
- In the other tool, a subscription (a service hook, a webhook, a flow…) tells SerenForce as soon as something is created. The hook decides which process to start.
- The process instance is started in your name, in your organization, with the people and values you chose for that process. It shows in Process instances like any other.
- Its name comes from a template, for example {Id} - {Title}: 1042 - Cannot sign in.
- The Integration of a hook (the tool that calls it) is chosen when the hook is created and cannot be changed afterwards: create another hook for another tool.
How is the process chosen?
The form has two tabs under How is the process chosen?:
- Manual configuration: you set the conditions yourself and choose one or several processes. A single process without conditions starts for every work item, issue, message or email. With several processes, put them in order: each has conditions, named as the tool names them (for example Work item types, Tags (at least one), Area path starts with for Azure DevOps; Issue types, Labels (at least one), Component starts with for Jira). The first process whose conditions the item all meets is started; an empty condition accepts everything. If none fits, nothing is started. A condition that means nothing for a tool is not offered (no tags for a Teams message, no area for an email).
- AI configuration: for each process you describe in a sentence what it is for (When is this process the right one?), and, in Instructions for the AI, you can add a prompt (2000 characters at most) that tells the AI what to look for and how to decide, for example security items never go to the support process. An AI reads the item, your instructions and your descriptions, then picks the process that fits, or none.
1. Create a hook
- Click New service hook
In the Service Hooks tab. The button only shows if you can manage service hooks and see processes.
- Integration
Choose the tool that will call the hook: Azure DevOps, Jira, Microsoft Teams, Outlook email or Custom.
- Connection
As soon as you pick the tool, the Connection section shows the URL to set in it so that its service hook (for example the web hook of Azure DevOps) calls SerenForce, with a button to copy it. For the tools that send a header (Azure DevOps, Teams, Outlook, custom) it also shows the name of the header, X-Hook-Secret. Set the URL in the tool, then save: SerenForce then generates an API key, shown only once, to send in the header X-Hook-Secret. The URL does not change when you save, and the tool you pick changes its address. When you edit a service hook, the same URL is shown with a button to open the connection details.
- Details
Give a Name (required) and, if you wish, a Name of the process instances using the fields received: {Id}, {Type}, {Title}, {Description}, {State}, {Url}, {Tags}, {AreaPath}, {AssignedTo}, {Project}, {Author}. By default the name is {Id} - {Title} for Azure DevOps and Jira, and {Title} for the others.
- Manual or AI configuration
Pick the tab (see How is the process chosen?).
- Process
Choose the published process, who plays each participant and the values of the variables. With Copy a field, a field received fills a variable of the process (the form explains what each field means for the tool). With Add a process, add other processes.
- Click Save
SerenForce shows what to give the other tool: the address and the secret.
2. Connect the other tool
After the creation (or with the Connect to… button of a hook), SerenForce shows the steps for the tool, the URL to call and how to prove who is calling. A tool can send the API key in one of three ways: in the header X-Hook-Secret (the way to prefer), as a bearer token, or at the end of the address (?secret=…, for tools that can only store an address). The API key is shown only once: copy it right away. Lost it? Use Renew the API key: a new API key is shown and the old one stops working.
Azure DevOps
- In Azure DevOps
Open Project settings › Service hooks › Create subscription and choose Web Hooks.
- Event
Choose Work item created (you can filter on the type or the area path).
- Address and authentication
Paste the URL; leave the authentication empty. In HTTP headers, add the header shown followed by the API key, written as X-Hook-Secret: your-api-key.
- Test it
The result of the last call shows on the hook.
Jira
- In Jira
Open Settings › System › WebHooks and choose Create a WebHook.
- Event
Choose Issue created (you can narrow the issues with a JQL query).
- Address
Paste the URL: when the hook has just been created it already holds the API key (?secret=…), because Jira cannot send a header. If the API key is no longer shown, renew it to get the full address.
- Test it
Create an issue: the result of the call shows on the hook. The Number field is the key of the issue (PROJ-12), Area path its first component, Project the key of the project and Author the reporter.
Microsoft Teams
- In Teams
Open Workflows and create a flow from the trigger When a new channel message is added.
- Call SerenForce
Add the action HTTP with the method POST and paste the URL.
- Authentication and message
Add the header shown (X-Hook-Secret) with the API key, and send the message as the body: its text, its sender, its channel and its link.
- Test it
Post a message in the channel. Title is the subject or the first line of the message, Area path the channel, Project the team and Author the sender.
Outlook email
- In Power Automate
Create a flow from the Outlook trigger When a new email arrives (V3); choose the mailbox and, if you wish, filter on the folder, the sender or the subject.
- Call SerenForce
Add the action HTTP with the method POST and paste the URL.
- Authentication and email
Add the header shown (X-Hook-Secret) with the API key, and send the email as the body: subject, body, sender, importance, categories and link.
- Test it
Send yourself an email. Title is the subject, Type the importance (low, normal, high), Tags the categories, Assigned to the first recipient and Author the sender.
Custom
For any other tool that can send data (an HTTP POST with a JSON body) to an address. Since SerenForce cannot know where each piece of information is in what the tool sends, you tell it in the section Where are the fields? of the form: for each field, the path in the JSON, for example issue.key or items[0].title. Fill in at least one path and leave the others empty.
- In your tool
Send a POST request with the JSON of the event to the URL each time something happens.
- Authentication
Add the header shown (X-Hook-Secret) with the API key, or use a bearer token.
- Test it
The result of the last call shows on the hook; check that the paths find their values.
3. Follow and manage your hooks
The Service Hooks page lists your service hooks: their tool, how they choose, their processes, their state (Active or Paused), the last call and its result:
- Process instance started: an instance was started (the Open the last process instance button opens it).
- No process found: no rule fitted (or the AI found nothing); nothing was started.
- Ignored: the event was not a creation (an update, a comment…).
- Failed: the instance could not be started (process no longer published, AI unavailable…); the message shows on the hook.
- Pause / Resume: a paused hook refuses the calls of the other tool.
- Test (debug mode): only when SerenForce runs in debug mode, on a developer's machine. SerenForce sends the service hook what its tool sends when something is created, as a real call, with a work item that meets the conditions of its first process. A message tells what happened, and the last call of the hook shows it. This button is never shown in the deployed application.
- Edit: change the name, the configuration (manual or AI), the conditions, the descriptions, the instructions for the AI and, for a custom service hook, the paths. The tool, the process, the people and the values of a process already in the hook do not change: remove the process and add it again.
- Delete: removes the hook (the other tool will get an error). The instances already started are kept.
Good to know
- Each hook keeps the published version of the process chosen when it was created: publishing a new version changes nothing until you edit the hook.
- The AI configuration sends an AI the title, description, tags and area (or channel, component…) of the item, with your descriptions and your instructions. It is only available if the administrator of the platform configured it; otherwise the hook shows Failed.
- An API key in an address (?secret=…) can end up in the logs of the tools in between: prefer a header whenever the tool can send one.
- A name or a value that is too long is cut (200 and 250 characters).
Permissions
- See the Service Hooks page: View service hooks. Everyone only sees their own hooks.
- Create, edit, pause, renew the API key and delete: Manage service hooks (and View processes to choose the processes). Users and roles explains how to get them.