Documentation › Hooks

Start a process from Azure DevOps: hooks

A hook is an address that Azure DevOps calls when a work item is created (a bug, a PBI…). ProcNest then finds the right process and automatically starts a process instance, with the title of the work item in a variable if you wish.

What is a hook for?

• In Azure DevOps, a subscription (service hook) tells ProcNest as soon as a work item is created. The hook decides which process to start.
• The process instance is started in your name, in your team, 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.

How is the process chosen?

Set How is the process chosen?:

• One process: every work item starts the same process.
• Rules: you add several processes, in order. Each has conditions (Work item types, Tags (at least one), Area path starts with). The first process whose conditions the work item all meets is started; an empty condition accepts everything. If none fits, nothing is started.
• AI: for each process you describe in a sentence the work items it is for (When is this process the right one?). An AI reads the work item and picks the process that fits, or none.

1. Create a hook

1. Click New hook

   In the Hooks tab. The button only shows if you can manage hooks and see processes.

2. Details

   Give a Name (required) and, if you wish, a Name of the process instances using the fields of the work item: {Id}, {Type}, {Title}, {Description}, {State}, {Url}, {Tags}, {AreaPath}, {AssignedTo}, {Project}.

3. Process

   Choose the published process, who plays each participant and the values of the variables. With Copy a field, a field of the work item fills a variable of the process. With Add a process, add other processes (Rules and AI).

4. Click Save

   ProcNest shows the address to give to Azure DevOps and the secret.

2. Connect Azure DevOps

After the creation (or with the Connect to Azure DevOps button of a hook), ProcNest shows what to copy:

1. In Azure DevOps

   Open Project settings › Service hooks › Create subscription and choose Web Hooks.

2. Event

   Choose Work item created (you can filter on the type or the area path).

3. Address and authentication

   Paste the URL; copy the user name and the secret as the basic authentication.

4. Test it

   The result of the last call shows on the hook.

The secret is shown only once: copy it right away. Lost it? Use Renew the secret: a new secret is shown and the old one stops working.

3. Follow and manage your hooks

The Hooks page lists your hooks: 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 the creation of a work item.
• 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 Azure DevOps.
• Edit: change the name, the way of choosing, the conditions and the descriptions. The process, the people and the values of a process already in the hook do not change: remove it and add it again.
• Delete: removes the hook (Azure DevOps 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 way sends an AI the title, description, tags and area path of the work item, with your descriptions. It is only available if the administrator of the platform configured it; otherwise the hook shows Failed.
• A name or a value that is too long is cut (200 and 250 characters).

Permissions

• See the Hooks page: View hooks. Everyone only sees their own hooks.
• Create, edit, pause, renew the secret and delete: Manage hooks (and View processes to choose the processes). Users and roles explains how to get them.