Provisioning Site Collections without WorkPoint App Permissions

To complete the process described in this guide, you need to grant permissions to the WorkPoint Integration API.

You can do so by following this link: https://wp365integration.azurewebsites.net/

Then follow these steps:

1. Type in your tenant name. In this instance, you tenant name is "CalperIT".
2. Click the "Sign-up" button for "Daemon integration minimal permissions".

3. Type in your Office 365 login information.
4. Click the "Next" button.

5. Click the topics under "This app would like to" section to read more about what you grant permissions for the API to do.
6. Click the "Accept" button.

You should now see the following page:

We will now create an Azure Automation. We do this from the portal.azure.com portal.

Start by navigating to https://portal.azure.com and log in with your tenant administrator account.

Next, follow the steps:

7. In the Home dashboard in the Azure portal, click "Create a resource".

8. In the New Resource page, in the left menu click "IT & Management Tools".
9. In the list of resources, click "Automation".

10. Provide the Automation with a name. In this case, we name it "CalperIT-Automation".
11. Select a subscription to use with this automation. In this case, we are using a free trial subscription.
12. Select a resource group to place the automation in, or create a new one.
13. Select a location for the automation.
14. Select "Yes" to creating an Azure Run As account.
15. Click the "Create" button to create the Automation.

The following messages will show up in the top right of the page after clicking "Create":

Refreshing the Home dashboard page should now display the newly created Automation:

The first step is to add the SharePointPnPPowerShellOnline module to an Azure Automation. This module is used by the WorkPointPSCmdlets module to facilitate the site provisioning:

16. Click the newly created Automation to open it.

17. In the left menu, in the "Shared Resources" section click "Modules gallery".

18. Perform a search for "SharePointPnPPowerShellOnline".
19. Select "SharePointPnPPowerShellOnline".

20. In the "SharePointPnPPowerShellOnline" page click "Import".

This will import the SharePointPnPPowerShellOnline module to the Automation. This operation may take several minutes as stated in the following message which is displayed when the operation is started:

Clicking the "OK" button takes you to the following page:

Once the module is imported successfully, it should appear in the "Modules" page with a status of "Available":

Next, we will import the WorkPointPSCmdlets module:

21. Go back to the "Modules gallery" page.
22. Perform a search for "workpoint".
23. Select the "WorkPointPSCmdlets" module.

24. Click the "Import" button to import the module.

We now have to wait until the module is imported. The process is the same as for the SharePointPnPPowerShellOnline module.

Once it is successfully imported it will appear in the Modules page with a status of "Available":

Next, we will import the demo scripts provided by WorkPoint. As previously mentioned, it is possible to create custom scripts, however WorkPoint does not provide support for custom scripts.

We start by navigating to the Runbooks section:

25. In the left side menu, under Process Automation, click "Runbooks gallery".

26. In the Source drop down menu, select "PowerShell Gallery".
27. Perform a search for "workpoint".
28. Select the "WPBucketSiteProvisioning" script.

29. A preview of the script can be inspected.
30. Click the "Import" button to import the script.

31. If you wish to rename the script you can do so in the Name field.
32. Similarly to the name you can change the description of the script.
33. Click the "OK" button to import the script.

In the same way, we import the WPEntitySiteProvisioning script:

34. In the Runbooks gallery, select and import the WPEntitySiteProvisioning script.

Once imported, the scripts appear in the "Runbooks" section:

35. In the left side menu, under Process Automation, click "Runbooks".
36. The two imported scripts should appear in the list.

Next, we need to publish the scripts. This is necessary if the scripts are to be called from other scripts, run on a schedule, etc.

We will now publish the two scripts:

37. Click the script which is to be published.

38. In the script's page, click the "Edit" button.

39. In the Edit page, click "Publish".

40. In the Publish Runbook dialogue, click "Yes".

The published script should now appear as such in the Runbooks list:

The process for publishing the other WorkPoint script is the same. Once both are published, they should both appear with the "Authoring status" of "Published":

We have now successfully created an Azure Automation, added the SharePointPnPPowerShellOnline and WorkPointPSCmdlets modules and the two Runbook scripts.

In the next section we need to register our App and extract some variables for later use.

In order to register our App, we navigate to https://aad.portal.azure.com. Then follow the following steps:

41. In the Azure Active Directory admin center, in the left menu, click "Azure Active Directory".
42. In the Azure Active Directory menu, click "App registrations".
43. In the App registrations page, click "New registration".

44. Provide a name for the app registration. In this case, we name it "CalperIT".
45. For Supported account types, select the "Accounts in this organization directory only" option.
46. Click the "Register" button.

47. In the overview page for the app registration, copy the Application (client) ID and paste it into e.g. a notepad document, as you will need it later.
48. Now go to the "API permissions" page.

49. In the API permissions page, click "Add a permission".

50. In the Request API permissions side panel, select the "APIs my organization uses" tab.
51. Perform a search for "WorkPoint365 integration" or something close.
52. In the list of APIs, select "WorkPoint365 Integration".

53. In the Request API permissions for the WorkPoint365 Integration API panel, select "Application permissions". Permissions of this type means that the application may perform actions using the API with it's own permissions.
54. Check the "ApplicationAccess" permission.
55. Click the "Add permissions" button.

The WorkPoint365 Integration permission should now show in the list of Configured Permissions, as shown in the following image:

We now have to actually grant permissions to the WorkPoint365 Integration API. Follow these steps:

56. Below the list of configured permissions, click "Enterprise applications".

57. Click the "Grant admin consent for CalperIT" button.

58. Sign in with your Office 365 login.

59. Click the "Accept" button.

Upon successful granting of the permissions to the WorkPoint365 Integration API, the API Permissions page should now show that the permission is granted:

Next, we need to create a so-called "secret". This secret is the password used for accessing the WorkPoint API and should ultimately be stored in some sort of password manager, such as SecretServer:

60. In the overview page for the app registration, click "Certificates and secrets".
61. Click "New client secret".

62. Provide a description for the new secret.
63. Select when the secret should expire. In this example, we select that the secret expires after 1 year. Once expired, a new secret needs to be generated.
64. Click the "Add" button to create the secret.

The secret should now appear in the list of Client secrets:

65. Copy the "Value" for the secret and store it in a secure location, e.g. SecretServer or another password manager. This value is the password used to access the WorkPoint API. You can click the clipboard icon to copy the entire value - remember to paste it somewhere where you can find it later.

Next, we need to configure these variables in Azure.

We will now import the variables from the App Registration as well as other variables into the Azure Automate we created in section 3.1:

66. In the Azure Automation we created earlier, in the side menu, click "Variables".

This is where you can store some of the variables which you do not want to enter each time, but still want to store separately from the runbooks (in case you have more runbooks, etc.).

67. Next, click "Add a variable".

Here we add the Application (client) ID which we copied in an earlier step:

68. We provide a name for the variable. This the variable name we will use to call the value from scripts.
69. We also add a description of the variable.
70. We set the type of variable to "string" because our value is a collection of letters, numbers and symbols.
71. In the Value field, we paste in the Application (client) ID we copied earlier.
72. WorkPoint recommends to set Encryption to "Yes". This will make it so that the value is shown as asterisks instead of the actual value in the list after creation. the script still reads the value correctly, but it prevents anyone from obtaining the value by physically looking at the list. Note, however, that this option cannot be changed later, so if you need to be able to see these values, you should not encrypt them.
73. We now click the "Create" button to create the variable.

The variable now appears in the list of variables:

In the same way as before, we add a variable for the Client secret we created, as well as a variable for our WorkPoint solution URL:

After this, we need to add one more variable: the WorkPoint App ID. We will describe how to find this here:

74. In your SharePoint Administration center, go to your list of Active sites.
75. Search for and locate your App Catalog. In this example, our app catalog is called "AppCatalog". Click to open your App Catalog site.

76. In the App Catalog site, click "Apps for SharePoint".
77. Copy the Product ID of your WorkPoint App without the curly braces.

We will now create a new variable in our Azure Automation for this value:

Next, we will set up the credentials for the user account which will be used for actually provisioning the site collections:

78. In the Azure Automation side menu, click "Credentials".
79. Click "Add a credential".

80. Provide a name for the credential.
81. Type in a description for the credential.
82. Type in the user name of the credential.
83. Type in and confirm the password for the credential.
84. Click the "Create" button to create the credential.

The credential should now appear in the list of credentials:

We have now set up what we need to create a new Runbook.

In this example, we will use the RunCreateBucketSite script to create a new site collection for a business module using the Multiple entities per site collection architecture in WorkPoint:

85. In the Azure Automation side menu, under "Process Automation", click "Runbooks".
86. Click "Create a runbook".

In the following example, we set up a runbook to create an entity site on the business module we specify:

87. Provide a name for the Runbook. You should try to make the name informative as to what the runbook does.
88. For Runbook type, select "PowerShell".
89. Optionally provide a description of what the runbook does.
90. Click the "Create" button to create the runbook.

We are now taken to the runbook editor. Here we can type in code which will execute when the runbook is run.

In the RunCreateBucketSite example, WorkPoint provides the following example script:

This script will, once we substitute a couple of variables into the script, create a new bucket site collection on the solution we specify.

First in the script is a set of variables corresponding to the variables created earlier in this guide, as well as the credential we created.

Note that the variable name in the script (the names in quotation marks) must correspond with the variable names you created for your variables.

In this example we will use the example script to create a new bucket site in WorkPoint, so we copy the script and insert it into the runbook editor. Note that in line 7 of the script, we substitute "[Your Business Module ID]" with "e3ac87b7-03f6-489e-b3bd-3d21d8275d8e" (which is the ID of the Companies" business module on our WorkPoint solution, and for the "-newSiteUrl" parameter, we type in "https://calperit.sharepoint.com/sites/ProjectManagement_Companies3" (which is the location where we want the new bucket site to be created).

The full script will then be the following:

You can find your business module ID by going to the business module list settings, and looking in the URL. The string after "List=" is your business module ID, as shown in the following image:

Next, we need to save and publish the runbook:

91. We first click the "Save" button to save the runbook.

92. We then click the "Published" button to publish the runbook.

93. In the dialogue box, we click "Yes" to publishing this version of the runbook and override previously published versions (there are none at this point).

We can now try to run the runbook and create a site collection on our WorkPoint solution.

94. To start the runbook, click the "Start" button.

95. Confirm that you wish to run the runbook.

96. The runbook starts in the "Queued" status.
97. Click the "Refresh" button periodically to follow the status of the runbook execution.

Eventually the status should change to "Running":

Finally, once the execution of the runbook is complete, the status should change to "Completed":

In the Job Queue Manager in the WorkPoint Administration, we should now see a Site Collection Registration job running:

After a while, we should also be able to see the new site collection in the Site Collection Administration page in the WorkPoint Administration:

Eventually, the status of the site collection should change to "Ready":

The site collection is now ready for use next time we need to create a site collection for the Companies business module.

The "RunCreateEntitySite" script is used for creating site collections on business modules using the One entity per site collection architecture. In this example we have a business module called "Projects" with this business module architecture, on which we are going to create a new site collection.

We will start by creating a new runbook:

98. In the Runbooks section, click "Create a runbook".

99. We type in the name "RunCreateEntitySite" for the runbook.
100. We select the PowerShell Runbook type
101. Optionally, we can type in a description for the runbook. In this example we skip this.
102. We click "Create" to create the runbook.

The script we use to create an entity site to be used for business modules with the One Entity per Site Collection architecture is the following:

Note that this is the example we use with our specific WorkPoint solution. To make this script work for your own solution, you will need to change the following:

• Change the -wpBusinessModuleId value to correspond with the business module on which you wish to create the site collection
• Change the -newSiteUrl value to match the location fitting for your solution. Note that in this example, we have created a variable ($rnd = Get-Random) which generates string of random numbers which we append to the business module (because we add the variable to the end of the -newSiteUrl value).
• You should also select a new name for the site collection by setting the -NewSiteTitle value.

For information about how to set up the variables in the top of the script please refer to the previous steps in this guide.

We can now save and publish the runbook:

103. Click the "Save" button to save the runbook.

104. Click the "Publish" button to publish the runbook

105. Confirm the publish by clicking "Yes".

We can now run the runbook:

106. Click the "Start" button to start the runbook.

For the steps between starting the runbook until it is completed, please refer the the images from the Create Bucket Site example here.

When the runbook execution is complete, the following job should appear in the Job Queue Manager:

Once the job is complete, the site collection should be visible in the Site Collection Administration:

When the site collection is ready for use, the Status is changed to "Ready":

Creating site collections as is done in section 3.4. and 3.5. can also be done using PowerShell.

For this to work, we need to import a couple of modules and scripts.

We start by opening Windows Power Shell in Administrator mode:

107. In the Windows search bar, search for "power shell".
108. For Windows Power Shell, select "Run as Administrator".

In Windows Power Shell, run the following commands one by one in sequence:

If you have not yet done any configuration related to PowerShell, you might get prompted to accept to install modules from untrusted repositories. Follow the instructions provided in PowerShell.

If the modules were installed correctly, you should be able to see them in the the list when running the following command:

The modules should appear in the list:

Same goes for the scripts by running the following command:

Here, the scripts should appear in the list:

When the modules and scripts are installed correctly, we can run the scripts as we did in the Azure portal.

For example, running the following command in PowerShell:

This command in PowerShell will execute the script to create a new Site Collection in the WorkPoint system at the location and with the name specified.

PowerShell provides the following messages upon executing the command:

The last line informs us that the site has been registered. We can see the job running in the Job Queue Manager in WorkPoint:

Once the job is done, we can see the newly created site collection in the Site Collection Administration in WorkPoint:

To use the site collections created by the ways explained in this article as buffer site collections, we can enable a setting called "Enable Site Collection Buffer". If enabled, the site collections are used for new entities created on the business module on which they reside:

109. In the Site Collection Administration, click "Enable Site Collection Buffer".

The button should now read "Disable Site Collection Buffer":

Now that we have enabled Site Collection Buffer, site columns, site content types, and a range of other various things are replicated to the site collections from the master site collection. The specific things being replicated are:

• Default Site Collection Settings
• Site Columns
• Content Types
• Language Resources
• Site Collection Term Group
• Site Collection Features
• Apps

By this time, these site collections do not have any specific lists replicated onto them and consists of the standard SharePoint contents. From here they can be used to create sites for entities in WorkPoint.

In addition to making the site collections ready for use, we can also use the Site Collections created in conjunction with Buffer Sites for specific modules.

In this example, we will work off of the previous configuration, but we have re-generated some site collections, with the names "EntitySite_06" "EntitySite_07", and  "EntitySite_08" which are available in the Site Collection Administration (although only the site collection names are shown):

Note here that the site collections are in the "Ready" state.

From here, we can enable Buffer Sites on e.g. our Projects module:

110. In the WorkPoint Administration, click the header of the business module for which Buffer Sites should be enabled. In this case, that is the Projects module.
111. Click "Buffer Sites".

112. Click the Buffer Sites checker to enable Buffer Sites for the module.
113. Type in a number for how many buffer sites you want to be ready for usage at any given time. (If you have 3 ready and one gets used, the system will automatically generate a new one to keep the number of buffer sites ready at 3). In this case, we select to have 3 buffer sites for this module.
114. Click the "Save" button.

The WorkPoint System would normally start by creating new site collections for the module, but since we already have Site Collections ready to go, these will be used for buffer sites. These should relatively quickly appear in the list of buffer sites:

Note that once these site collections are being used as buffer sites, their status in the Site Collection Administration changes from "Ready" to "InUse":

We can now use the buffer sites to create sites for new entities on the Projects business module. We we can see in the following image, one of the site collections have been used to create the following Project entity site: