A common integration scenario is the need to allow an end user of the portal to select a user, and then have orchestrator do something with the user that was selected.
For example, lets say you have an onboarding new hire request, and you want the end user filling out the request to select who the new hire’s manager will be, and then you use orchestrator to send an email to the new hire’s manager when the onboarding process is complete.
In Service Manager you can create a request offering including a query prompt that allows the user filling out the request to select an object such as a user. (Check my incident on behalf of blog for more on that )
When you need to pass the results of a query prompt from a Service Manager Service Request or Incident to Orchestrator, there are 2 options:
1) Extend the Class with a custom relationship in the Authoring Tool (For Example – If creating a service request specifically for onboarding, you may create a customized ‘New Hire Onboarding Service Request’ Class which has the extended relationships ‘newHireMentor’ and ‘NewHireManager’.
2) Use the checkboxes in the Configure Query Results>Options Page:
- Add user-selected objects to template objects as related items
- Add user-selected objects to template object as configuration items.
This second option takes advantage of using built-in relationships that already exist between classes, removing the need to create custom relationships with the authoring tool.
Once you have these values propagating into the Service Request / Activity relationships, they are easily accessible and usable within an orchestrator runbook.
However the forgettable part can be which relationships these checkboxes map to. So this blogpost is mostly for reference to help with this.
First off, lets look at the relationships that are available in Orchestrator. I find the easiest way to do this is to create a test runbook, and add a ‘Create Relationship’ Activity to the runbook. Then add the two classes you want to see relationships between (Service Request and Active Directory User in the example below) and then click the dots next to Relationship type to reveal the Item Selection box:
Service Request <> AD User Relationships:
Here are some other examples:
Manual Activity <> AD User Relationships:
Review Activity <> AD User Relationships:
Runbook Automation Activity <> AD User Relationships
Ok, so now in Service Manager, lets look at the Query Results Options page (in the request offering configuration) where you can populate these relationships:
One important note here is that you may initially think that only 2 relationships can be used, as initially you just see the two checkboxes. However, as you add more activities to the Request, those activity relationships can also be used, by changing the dropdown from the SR to the appropriate activity as shown here:
The final challenge is putting this all together, to know which of these checkboxes in Service Manager relates to which relationship in orchestrator. The following diagrams illustrate this for reference (Please click on the diagram to make it bigger if needed):
Service Request Relationships:
Manual Activity relationships
Note, although you can choose the top-box for mapping to the ‘related items’ relationship of the manual activity, you will not see this in the default manual activity form. It will be stored as such in the back-end (and accessible and usable by Orchestrator) but you would need to create a custom manual activity form to see that relationship. So if you want to see the selection in the manual activity, be sure to use the ‘Affected configuration items’ bottom check-box.
Review Activity Relationships
Note you will not see this in the review activity but they are stored in the back-end and will be available in Orchestrator
Runbook Automation Activity Relationships:
Once you know which relationship you want, you can use it in orchestrator. Note however when you use the Get relationship activity to get a service request, it will get ALL of the relationships associated with the Service Request. There is nowhere in the Get Relationship tool to specify which relationship you want to get, so it just gets all of them:
Therefore in order for the Orchestrator activities after the ‘Get Relationship’ to only act on the relationship you want, it is necessary to exclude all the relationships you don’t want in the ‘Exclude’ page of the preceding link, as shown below:
In the above example, the ‘Related to config item’ Get Object will only return the ‘Is related to Configuration item’ related user The ‘About config item’ Get Object will only return the ‘About configuration Item’ related user.
A runbook like the example one above, can tell you which user is which, as shown in the platform events here:
Enjoy using these relationships