PowerShell for SCSM: Submit Documents for Approval
Have you wanted to have a review activity that has attachments on it. This was a requirement for a customer that was using a Service Request to submit documents that needed to be approved. But review activities and the out of the box notifications do not support attachments.
By using a combination of the Xapity tools Notification Activity and PowerShell Activity, we can achieve this. This could also be achieved using Orchestrator as well, but would be a lot more complicated. The purpose of this blog post is to show you the steps involved and the PowerShell script to achieve it.
End user can select the Approver in the portal Service Request
End user uploads 1 document to be approved (this could be extended by adding extra upload options to the request offering)
Approver receives email with the document(s) for approval
Approver can reply by email to approve the document
Use the HTML 5 Portal to capture the End User input - Approver and the uploaded Document. This allows for a dynamic approver rather than one hard coded on the Review Activity.
Use the PowerShell script from the blog post "PowerShell Scripting: Copy parent Attachments to Child Activity" to get the attachments from the Service Request and copy them to a Notification Activity.
Use a PowerShell activity to add the Approver selected in the SR to the Review Activity using the blog post "PowerShell Scripting: Copy Approvers to Child Review Activities" as the starting point.
Use a PowerShell activity to get the Review Activity Id and store it on the Service Request (requires string property on Service Request)
Use a Xapity Notification Activity to send out a Review Activity approval email with the attached document uploaded by the user
Make sure that normal RA subscriptions exclude this type of Review Activity
Use the Exchange Connector to monitor the reply address of the email notification for the approval
The trick to the solution is have the Xapity Notification Activity send out the approval email rather than have a subscription based on the actual Review Activity. This allows us to send a copy of the attachments to the reviewer.
The other trick is to include the Review Activity Id in the subject of the email sent out by the Notification Activity. As the Notification Activity uses the parent context (ie Service Request) we need to use PowerShell to get the Review Activity Id and store it on the Service Request in a string property. Then the email template used by the Notification Activity (that is based on the SR) can display the correct information when it sends out an email to the approver.
The Service Request class has to be extended to store the Review Activity Id. This is just a string field and you could use an existing unused string field on the Service Request, like Notes, but it is better if you have one already. In the script below I have used a property called "SRString". This will need to be updated for your environment.
A recommendation would be to use Work Item Activity Tags on the Review Activity. This makes it easier to target the Review and Notification Activities in PowerShell. It also makes it easier to stop other Review Activity subscriptions from triggering against the Review Activity used on the document approval Service Request.
However, in the script below I will use a keyword in the title of the Review Activity and Notification Activity. This is easy to implement, but has a higher chance of mistakes happening (wrong words used, being deleted etc)
The consists of a Portal Request Offering based on a Service Request Template with the activities configured to process the information from the Portal.
The solution uses the Service Manager Portal to allow an end user to upload an attachment (document) and to choose the document approver. This is a standard Request Offering with the following user Prompts:
Title (this is optional)
Business Reason Mapped to the Service Request Description and can be included in the email template used by the Notification Activity. Again optional.
Approver - AD User Object that is stored against the Service Request as a related item
Upload document prompt
Service Request Template
The request Offering is based on a Service Request template that has the following activities:
Activity 1: PowerShell Activity
The PowerShell script below:
Copies the Review Activity Id to a string field on the Service Request
Copies the Approver selected and stored against the Service Request to the Review Activity Approvers
Copies all Attachment(s) on the Service Request to the Notification Activity
Sets Approver email address on the Notification Activity
The full script is below. It does not have an error control in it and if it finds a blank value in any of the required fields it will fail.
The high level outline is:
The Variable ParentID comes from the Xapity PowerShell Activity. This only needs to be set when the script is running by another method.
This takes up the first part of the script and is used to document in the Service Request the actions that are taking place. This is optional and can be removed, along with the commands in the script, if not required. For more explanation see the Xapity Action Log post.
Define Classes and Relationships
The script defines the classes and relationships used. This includes;
Note: the email address of the Approver is stored as a related object of the User CI. There can be more than one type of address and usually there are at least SMTP and SIP objects.
It gets all the Activities on the SR. This is a done by getting all related objects which is very broad and so I have excluded action log and file attachments.
For Loop through each Activity
This is the main work block of the script. The script uses an IF statement to look for a keyword in the Title of the Activity (related Object) and this way can determine if the current activity is a Notification Activity or a Review Activity.
Notification Activity Updates
It copies the all the attachments from the parent Service Request. As this is a For loop it would also be possible to use an IF statement to exclude some attachments that meet a certain criteria. But in this case it copies all attachments. See our blog post Copying attachments for more details.
The approver email address is also required on the Notification Activity. The script loops through the related objects on the DocumentApprover looking for an SMTP channel. It then updates (overrides) the Recipient property on the Notification Activity.
And finally adds a comment to the Service Request action log. Refer to the post "SCSM Updating the Action Log" for more information.
Review Activity Updates
First it takes the Review Activity ID and stores it in the SRSting property on the Service Request. You can use any string value and this will need to be updated in the script.
Then it takes the Approver chosen on the portal and adds it to the Review Activity. The user chosen on the portal is stored as a related item on the Service Request, if you store this against the Review Activity you will need to make a change this in the section "Define Classes and Relationships", where the ParentObject (SR) is used to define the DocumentApprover.
And finally it updates the Review Activity title with the title of the Service Request. This is optional and may have implications as it wipes out the keyword on the Review Activity (which may be used to exclude the RA from other email subscriptions)
Activity 2 : Notification Activity
The Notification Activity has the email template (based on the SR) that is will use and not much else. The PowerShell Activity above will populate the Recipient field with the approver from the portal and also copy any attachments from the Service Request.
This is a very basic email template that was used in this example - it just has approve and reject on it. I would include more details from the Service Request such as Description (business reason) and the end user requesting the approval.
But the key for the purposes of the example is that the SRString value (Review Activity ID) is being used for where you would have a work item ID. It uses an HTML formatted email so that the approver can just click on the link in the email and send back an approval email to a mailbox monitored by the Exchange Connector (SYS-SCSM_Workflow in this case)
Document Approval Required: [$Context/Property[Type='CustomServiceRequestClassExtension!ClassExtension_cabba04e_33c4_46b9_8129_7d12572235dc']/SRString$]: $Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/Title$
<A HREF="mailto:SYS-SCSM_Workflow@Xapity.Lab?subject=[$Context/Property[Type='CustomServiceRequestClassExtension!ClassExtension_cabba04e_33c4_46b9_8129_7d12572235dc']/SRString$] Document Approved&body=[Approved] This document request has been approved.">Approve</A>
to confirm your approval of the Service Request.<BR>
<A HREF="mailto:SYS-SCSM_Workflow@Xapity.Lab?subject=[$Context/Property[Type='CustomServiceRequestClassExtension!ClassExtension_cabba04e_33c4_46b9_8129_7d12572235dc']/SRString$] Document Rejected&body=[Rejected] - Reject Reason: ">Reject</A>
to reject the Document. Please provide details or a reason for the rejection.<BR>
Activity 3: Review Activity
The Review Activity has been created with a blank Reviewers section as the PowerShell Activity will fill
this in with the Approver chosen on the portal.
In the script you can set the Has Veto and Must Vote options if required.
Activity 4: MA for other actions
This was just a place holder to represent the next action(s) to take place in the business workflow. In this case it just stops the SR from completing and allows me to have a look at what happened.
Download Script: DocumentApprovalSoftwareRequest.zip
Xapity PowerShell Activity The Xapity PowerShell Activity is an Activity for SCSM that enables PowerShell scripts to be run in SCSM. Automate more of your processes directly in SCSM. Scripts are stored and updated from a central script repository. The scripts execution output can be viewed and if a failure occurs, an email notification can be sent.
Xapity Notification Activity Enables Email Notifications to be sent directly from any System Center Service Manager (SCSM) workflow. With the Xapity Notification Activity, email notifications can have attachments, external and related recipients and can use Notification Templates
Xapity - Innovative Software for SCSM - Discover our Products