AvePoint Learn
Request an article
Contact support
Request an article
Contact support
English

Home > Appendices > Appendix E - Integration with ServiceNow > Create REST Message

Download this article

Create REST Message

To invoke AvePoint Cloud Governance APIs, you must create a REST message in ServiceNow by completing the following configurations:

REST Message Basic Information

Complete the following steps to start creating a REST message:

  1. Sign in to your ServiceNow instance with an account that has the admin role.

  2. On the left navigation pane, enter REST Message in the search box, and then click REST Message in the search results.

  3. On the REST Messages page, click New to open the REST Message – New Record page.

  4. On the REST Message – New Record page, complete the following configurations:

    • Name – Enter a name for the REST API.

    • Endpoint – Enter ${data_center_url}/requests.

      NOTE

      The data_center_url is a sample value, it is a variable, and you can enter a custom one. This will also be used in the next configurations.

    • Application – Click the Preview this record icon next to the Application field, and navigate to the Scope field on the Custom Application page. Make sure to copy this application scope to your Notepad, and it will be used in the Create System Properties and Run Script to Submit Requests sections.

Add HTTP Headers

Then, you need to add HTTP headers by completing the following steps:

  1. Under the HTTP Request tab, double click the text box, enter the name and values in the Name and Value fields as listed in the table below, and then click the Save button when you finish.

    NameValue
    ClientSecretEnter ${gao_api_clientsecret}. (This is a sample header name, and you can enter a custom name within ${xxx}.)
    Content-TypeEnter application/json.
    UserPrincipalNameEnter ${gao_user_name}. (This is a sample header name, and you can enter a custom name within ${xxx}.)

  2. After you add all HTTP headers, click Submit and you will be redirected to the REST Messages page.

Add HTTP Methods

Then, you need to add HTTP methods for the REST message by completing the following steps:

  1. On the REST Messages page, click the message you’ve just created.

  2. Navigate to the HTTP Methods field and click New to open the HTTP Method – New Record page. Then, configure the following fields:

    • Name – Enter a custom name for the HTTP method.

    • HTTP Method – Select POST from the drop-down list.

    • Endpoint – Enter the endpoint that this REST message is sent. The endpoint URL varies with a service type, you can refer to the endpoint URL listed in the table below for different service types:

      Service TypeEndpoint URL
      Invite new guest user serviceEnter ${data_center_url}/requests/createguestuser.
      Create group/team serviceEnter ${data_center_url}/requests/creategroup.
      Change group/team serviceEnter ${data_center_url}/requests/changegroup.
      Team lifecycle management service – Restore teamEnter ${data_center_url}/requests/restoregroup.
      Team lifecycle management service – Delete teamEnter ${data_center_url}/requests/deletegroup.
      Team lifecycle management service – Archive teamEnter ${data_center_url}/requests/archivegroup.
      Team lifecycle management service – Change group team site storageEnter ${data_center_url}/requests/changegroupquota.
      Team lifecycle management service – Change team policyEnter ${data_center_url}/requests/changegrouppolicy.
      Team lifecycle management – Extend team leaseEnter ${data_center_url}/requests/extendgroup.
      Create site collection serviceEnter ${data_center_url}/requests/createsite.
      Change site collection settings serviceEnter ${data_center_url}/requests/changesite/setting.
      Site collection lifecycle management service – Delete site collectionEnter ${data_center_url}/requests/deletesite.
      Site collection lifecycle management service – Unlock site collectionEnter ${data_center_url}/requests/unlocksite.
      Site collection lifecycle management service – Lock site collectionEnter ${data_center_url}/requests/locksite.
      Site collection lifecycle management service – Archive site collectionEnter ${data_center_url}/requests/archivesite.
      Site collection lifecycle management service – Extend site collection leaseEnter ${data_center_url}/requests/extendsite.
      Site collection lifecycle management service – Change site collection storageEnter ${data_center_url}/requests/changesitequota.
      Site collection lifecycle management service – Change site collection policyEnter ${data_center_url}/requests/changesitepolicy.

  3. When you finish, click Submit. Then you will be redirected to the REST Message page.

Test the API

To test the API you’ve just added, complete the following steps:

  1. Navigate to the HTTP Methods field, and click the HTTP method you’ve just created.

  2. On the HTTP Method page, navigate to the Variable Substitutions tab, and then click New to open the Variable Substitutions – New Record page.

  3. Configure the Name and Test value fields.

    Repeat the steps above to add all variable substitutions as listed in the table below:

    NameValue
    data_center_urlEnter https://go-api.avepointonlineservices.com if the AvePoint Cloud Governance environment you are using is the production environment for commercial use.
    Enter https://governance-api-us-gov.avepointonlineservices.com if the AvePoint Cloud Governance environment you are using is the production environment for U.S. Government Public Sector.
    gao_api_clientsecretEnter the client secret that you copied in the Manage API Authentication Profiles section.
    gao_user_nameEnter the sign-in name of an AvePoint Cloud Governance user.
    Make sure the user has been added to AvePoint Online Services and has a subscription for AvePoint Cloud Governance.

  4. When you finish, click Submit. Then you will be redirected to the HTTP Method page.

  5. Navigate to the HTTP Request tab > HTTP Query Parameters, and enter the content in the Content field. See examples below for different service types.

  6. Click Test to test the AvePoint Cloud Governance API.

Create Team

This is a sample for a Create team service request API testing.

For more information about the script, refer to the schema provided by AvePoint Cloud Governance in the AvePoint Cloud Governance API.

{
	"groupDescription": "",
	"groupId": "DemoTeam",
	"groupName": " DemoTeam ",
	"members": [{
		"loginName": "Demo@domain.com",
	}],
	"owners": [{
		"loginName": " Demo@domain.com ",
	}],
	"policy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"primaryContact": {
		"loginName": " Demo1@domain.com ",
	},
	"secondaryContact": {
		"loginName": " Demo2@domain.com ",
	},
	"serviceId": " xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ",
	"summary": "DemoTeam",
	"teamsSettings": {
	},
	"templateSettings": {
		"enableCreateTeamFromScratch": true,
		"enableCreateTeamFromExistTeam": false,
		"enableCreateTeamFromTeamTemplate": false
	}
}

Change Team Settings

This is a sample for a Change team settings service request API testing.

For more information, refer to the schema provided by AvePoint Cloud Governance in AvePoint Cloud Governance API.

{
	"serviceId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"summary": "Test change team",
	"metadatas": [{
		"name": "Demo Metadata",
		"value": "Demo"
	}],
	"groupEmail": "DemoTeam@domain.com",
	"groupId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"groupName":"name changed",
	"originalGroupName": "name",
	"groupOwners": [{
		"action": 1,
		"displayName": "Demo",
		"loginName": "Demo@domain.com",
	}],
	"groupMembers": [{
		"action": 2,
		"displayName": "Demo1",
		"loginName": "Demo1@domain.com",
	}],
	"groupMetadatas": [{
		"action": 2,
		"name": "Demo Metadata",
		"value": "demo value",
	}]
}

Invite New Guest User

This is a sample content for an Invite guest user service request API testing.

For more information, refer to the schema provided by AvePoint Cloud Governance in AvePoint Cloud Governance API.

{
    "summary":"invite guest user",
    "userProperties":{
        "userName":"test@outlook.com",
        "usageLocation":"US",
        "jobTitle":"",
        "jobDepartment":"",
        "companyName":"",
        "manager":{
            "loginName":"Demo1@domain.com ",
        }
    },
    "welcomeEmailMessage":"test Welcome message", 
    "primaryContact":{
        "loginName":" Demo1@domain.com ",
    },
    "secondaryContact":{
        "loginName":" test@domain.com ",
    },
    "inviteGroups":[

    ],
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type":68, 
    "metadatas":[

    ],
    "oneTimeSettings":{
        "option":1,
        "durationType":0,
        "duration":3,
        "startTime":"2021-11-25T00:00:00.000Z" 
    },
    "questionnaireId":""
}

Team Lifecycle Management

This is a sample for a Team lifecycle management service request API testing.

For more information, refer to the schema provided by AvePoint Cloud Governance in AvePoint Cloud Governance API.

Restore team

{
    "summary":"Restore group",
    "serviceId":"xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupId":"xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupEmail":"Demo@domain.com"
}

Delete team

{
    "summary":"delete demoteam",
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupEmail":"Demo@domain.com"
}

Archive team

{
    "summary":"Archive Team",
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupEmail":"Demo@domain.com",
}

Extend team lease

{
    "summary":"extend group lease",
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupEmail":"Demo@domain.com",
    "extendDuration":50,
    "extendDurationType":0
}

Change group team site storage

{
    "summary":"change group quota",
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupEmail":"Demo@domain.com",
    "groupQuotaSize":"2"
}

Change team policy

{
    "summary":"change group policy",
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "groupEmail":"Demo@domain.com",
    "policy":{
        "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name":"demo_GroupPolicy"
    }
}

Create Site Collection

This is a sample for a Create site collection service request API testing.

For more information, refer to the schema provided by AvePoint Cloud Governance in AvePoint Cloud Governance API.

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "metadatas":[
        {
            "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "value":true
        }
    ],
   "summary":"Test Create SC",
    "siteTitle":"demoSC",
    "siteUrl":{
        "managedPath":"/sites/",
        "name":"demoSC",
        "root":"https://xxxx.sharepoint.com"
    },
    "timeZone":39,
    "language":2052,
    "policyId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "template":"STS#3#Team site (no Microsoft 365 group)#Collaboration",
    "deploymentManagerPlanName":"demo panel plan",
    "primaryAdmin":{
        "loginName":"Demo@domain.com"
    },
    "additionalAdmins":[
        {
            "loginName":"Demo@domain.com"
        }
    ],
    "primaryContact":{
        "loginName":"Demo@domain.com"
    },
    "secondaryContact":{
        "loginName":"Demo1@domain.com"
    },
    "userPermissions":[
        {
            "permissionLevels":[
                {
                    "name":"View Only"
                }
            ],
            "user":{
                "loginName":"test@domain.com"
            }
        }
    ],
    "groupPermissions":[
        {
            "name":"$SiteName Owners",
             "users":[
                {
                    "loginName":"test@domain.com"
                }
            ],
            "permissionLevels":[
                {
                    "name":"Full Control"
                }
            ]
        },
        {
            "name":"$SiteName Members",
            "users":[

            ],
            "permissionLevels":[
                {
                    "name":"Edit"
                }
            ]
        },
        {
            "name":"$SiteName Visitors",
            "users":[

            ],
            "permissionLevels":[
                {
                    "name":"Read"
                }
            ]
        }
    ],
    "leasePeriodSettings":{
        "leaseDurationType":0,
        "leaseInterval":100
    }
}

Change Site Collection Settings

This is a sample for a Change site collection settings service request API testing.

For more information, refer to the schema provided by AvePoint Cloud Governance in AvePoint Cloud Governance API.

{
    "summary":"change sc settings",
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "siteTitleSetting":{
        "changeValue":"demoPanel",
        "originalValue":"demoPanel"
    },
    "siteDescriptionSetting":{

    },
    "changedMetadatas":[
        {
            "action":1,
            "name":"Api_Sample_demo_SingleLine",
            "value":"test snow"
        }
    ],
    "deploymentPlanName":"demo panel plan"
}

Site Collection Lifecycle Management

This is a sample for a Site collection lifecycle management service request API testing.

For more information, refer to the schema provided by AvePoint Cloud Governance in AvePoint Cloud Governance API.

Unlock site collection

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Unlock SC"
}

Lock site collection

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Lock SC",
    "lockType":"0"  //0: no access      1:readonly
}

Archive site collection

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Archive SC"
}

Delete site collection

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Delete SC"
}

Extend site collection lease

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Extend SC",
    "extendDuration":50,
    "extendDurationType":0
}

Change site collection storage

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Change SC Quota",
    "quotaSize":2
}

Change site collection policy

{
    "serviceId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "siteUrl":"https://xxxx.sharepoint.com/sites/demoPanel",
    "summary":"TestSnow_Change SC Policy",
    "policy":{
        "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name":"demo SC Inactivity Policy"
    }
}

Create System Properties

To create system properties, complete the following steps:

  1. In your ServiceNow instance, enter System Properties in the search box on the left navigation pane, and then click Categories from the search result.

  2. On the System Properties Categories page, click New to create a new category or edit an existing category.

  3. On the System Property Categories – New Record page, enter the Name and Title for the category, and click Submit. Then, you will be redirected to the System Property Categories page.

  4. Search out the category you’ve just created, and click the category name to open the category configuration page.

  5. Navigate to the Properties field, click New to create new properties, or edit an existing property. Then configure the properties as the table below on the System Property page:

NameValue
x_avepo_cg_modern.gao_user_name
Note that this is a sample property name. You can enter a custom name in the format of "Application scope.Header name", and:
Replace the Application scope with the application scope that you copied in the REST Message Basic Information section.
Replace the Header name with the header name that you configured in the Add HTTP Headers section.		Enter the sign-in name of an AvePoint Cloud Governance user.
Make sure the user has been added to AvePoint Online Services and has the subscription for AvePoint Cloud Governance.
x_avepo_cg_modern.gao_api_clientsecret
Note that this is a sample property name. You can enter a custom name in the format of "Application scope.Header name", and:
Replace the Application scope with the application scope that you copied in the REST Message Basic Information section.
Replace the Header name with the header name that you configured in the Add HTTP Headers section.		Enter the client secret that you copied in the Manage API Authentication Profiles section.
x_avepo_cg_modern.data_center_url
Note that this is a sample property name. You can enter a custom name in the format of "Application scope. data_center_url", and replace the Application scope with the application scope that you copied in the REST Message Basic Information section.		Enter https://go-api.avepointonlineservices.com if the AvePoint Cloud Governance environment you are using is the production environment for commercial use.
Enter https://governance-api-us-gov.avepointonlineservices.com if the AvePoint Cloud Governance environment you are using is the production environment for U.S. Government Public Sector.