URL Parameters and Possible Responses

Dry Run

Dry Run is the ability to run the process of generating and storing the operations to sync your structure into Pluralsight without applying those operations within Pluralsight. This allows for a review of the data to ensure everything would appear as expected before making permanent changes to your Pluralsight Team Structure.

Note: The default behavior for this dryRun is true. This means that if you don't set dryRun to false it will default to not applying the changes in Pluralsight. It will return the generated operations that would be necessary for syncing your organization structure.

To apply the generated operations and officially bring your organization structure into Pluralsight, add ?dryRun=false to the end of your endpoint url.


Strict Mode (ExitOnError)

Strict mode is the ability to force the import/sync process to stop upon encountering any errors. This is likely most helpful when initially setting up and testing the import process. Without strict mode, the file validation process will document and then remove any records that would cause errors and move forward with the rest of the data to run the import. Strict Mode will stop the process from moving forward upon receiving any errors and not attempt to run the sync of your teams.

Regardless of whether you are using strict mode or not, the results of the validation and sync process can be viewed within the Team Sync Results page with further helpful information to be found within the Troubleshooting page.

Note: The default behavior for this exitOnError is false. This means that if you don't set exitOnError to true it will default to removing the users/teams that are causing the errors from the files and continuing with the rest of the validation and sync process.

To turn on strict mode and stop the process whenever errors occur, add ?exitOnError=true to the end of your endpoint url.


Turning off Manager Invites

This provides the option to run the sync process without inviting managers to Pluralsight via email. All of the other operations would be applied and you would be able to view your team structure within Pluralsight. Managers that are not already set up as users in Pluralsight would not be sent an email to invite them and will not be added to the team.

Below are some of the ways to decide what kind of email invites you want to turn off:

  • Disable manager emails through toggle button in the Pluralsight portal:
    • Invites are still generated and are available to view within the "Pending Invites" tab in Pluralsight but emails will not be sent out.
    • Can also stop email notifications from being sent to users that were already in Pluralsight that are added as managers.
    • Here's the Help Center Page that explains in detail how to turn off manager invites toggle button in the Pluralsight portal. Follow the instructions in the "Setting permission levels" section and you will see a toggle for "Disable manager invite emails when they're assigned to teams" toggle.
  • Disable managers invites via sendManagerInvites flag:
    • While invite operations will be generated, actual invites within Pluralsight will not be generated and no invites will be sent. Managers that already exist in Pluralsight as users will still get an email to come see their team analytics.
  • You can also do both (a) and (b) to stop any kind of invites/team view email going to managers.

The default behavior for sendManagerInvites is true. This means that if you don't set sendManagerInvites to false in the url it will default to sending email invites to managers that are not already in Pluralsight. It will also still send email notifications to the users that are now added as managers on teams.

Note: The manager invite process is part of the operations which means that it only occurs when the dryRun parameter is set to false. If dryRun is set to true, no manager email invites will be sent. The operation would be generated and stored but not applied.

This is achieved by adding ?dryRun=false&sendManagerInvites=false to the end of your endpoint url.


Syncing Only a Part of Your Organization/Retain Manually Created Teams

This functionality allows you to sync only parts of your organization that you want in Pluralsight. This allows you to send us all your data without any filtering if you choose and we will only look at teams that fall under the rootTeamId sent to us. Using this parameter also means that any manually created teams within Pluralsight (so long as they have a team name that is unique from any team name sent in the teams.csv file and/or do not fall under the rootTeamId in your hierarchy) will be left alone.

This option can be turned on by adding a rootTeamIds parameter to the url. The value(s) should be the id of the teams that are at the top level of the organization you want synced into Pluralsight. The id should match the id of the team in the teams.csv.

You have the option to send multiple rootTeamIds separated by commas(,). This is achieved by adding ?rootTeamIds=id1,id2 to the end of your endpoint url, with the id1,id2 being swapped out with the id of the top level org.


Strictly Exit the Sync Process due to Errors

This provides the option to validate the files sent over in a strict way that will stop the sync from running if any errors are found. With this option turned on it will only complete the validation of the files and will not make any changes to the team structure. It will also not generate the operations for the sync process. Errors that were found during validation can be viewed on the Team Sync Results page whether this functionality is turned on or not.

Note: The default behavior for exitOnError is false. This means that if you do not set the exitOnError to true in the url it will default to continuing the sync process with the errored records removed from the org structure.

This is achieved by adding ?exitOnError=true to the end of your endpoint url.



Possible Responses

If you've provided only the users file:

Copy
{
  “status”: “Awaiting teams file”
}

Status Code: 200 Content-type: application/json

Note: We do not begin data validation on either file until we have both files. Once both files have been provided you will either get a success or an error response with further information.


If you've provided both files:

Copy
{
  “status”: “processing”,
  “statusUrl”: “https://integrations-api.pluralsight.com/sync-users/:id/status”
}

Status Code: 200 Content-type: application/json

Note: You can then use the returned statusUrl to poll for status updates. See below.


If you have uploaded both files but provided invalid data or headers in one or both files:

Copy
{
  “status”: “Invalid data”,
  “errors”: [
    "Missing header(s) for [either users or teams] file: [list of headers missing]",
    ... 
  ]
}

GET /sync-users/:id/status

This endpoint allows you to request updates to a sync job using the url returned when you finished uploading both files.


Possible Responses

In Progress

Copy

{
  “status”: “processing”
  “dryRun”: true|false
}

Status Code: 200


Completed

Copy

{
  “status”: “completed”,
  “dryRun”: true|false,
  “listOfOperations”: [‘operation one’, operation two’],
  “errors’: []
}

Status Code: 200


Completed with Errors

Copy

{
  “status”: “completedWithErrors”,
  “dryRun”: true|false,
  “listOfOperations”: [‘operation one’, operation two’],
  “errors’: [‘error one’, ‘error two’, ...]
}

Status Code: 200


Full Example

Copy

curl 
  -T teams.csv
  -X POST
  -H “Authorization: Bearer [insert-your-api-key-here]“ 
  -H 'Content-Disposition: attachment; filename="teams.csv"'
  -H “Content-Type: text/csv“
    https://integrations-api.pluralsight.com/sync-users
curl 
  -T users.csv
  -X POST
  -H “Authorization: Bearer [insert-your-api-key-here]“ 
  -H 'Content-Disposition: attachment; filename="users.csv"'
  -H “Content-Type: text/csv“
    https://integrations-api.pluralsight.com/sync-users

Poll the statusUrl from the response of the previous request for updates

Copy

curl https://integrations-api.pluralsight.com/sync-users/:id/status 
  -H “Authorization: Bearer [insert-your-api-key-here]”

Note: In this example, we used Bearer auth, but you could have used Basic Authentication instead. See Authentication above for details.