Change Sets

a change set is used to track configuration changes made on a servicely instance/environment (i e development, test, production), into a deployable package a change set, being a deployable package, can then be exported off a servicely environment you did your changes on, and imported onto another servicely environment such as a production, without the need to duplicate effort/manually re doing your changes we will refer to the servicely environment that you do your changes on, as the “source servicely environment” (which is typically a development or test environment) we will refer to the servicely environment that you deploy your changes onto, as the “target servicely environment (which is typically a test or production environment) tracking changes to start off the process, you first need to track the changes the below sections how the changes you made can be tracked creating and activating a change set navigate to “administration” > “administrator tools” > “change sets” click on "new" provide it with name that is relevant to the changes you are tracking it should be unique, so often including a reference number or otherwise makes sense when possible if you want to only create the change set but not have it immediately selected, i e configuration changes will not be tracked against that change set, then, click “create” if you want to create the change set and have it immediately selected, i e configuration changes will be tracked against that change set, then, click “save & activate” switching between change sets your selected change set will show in the dropdown to the right of the change set's "tracking" mode picker to list all open change sets, click on the change set dropdown field you can also view a change set's details and the changes it has tracked so far, by clicking on the "new window" icon to the right of the change set's name an example below shows what a change set record can look like with its changes the list of changes contains columns including “changed table” and “record id” showing which configuration table and which configuration record was created/updated as well as what the operation (create vs update vs delete) was to switch to another change set that you want your changes to be tracked on, click on the dropdown field and select the change set you want your changes tracked on after the dropdown field goes back into its collapsed state, it will show the change set you had just switched to default change set every servicely environment comes with a default change set as there needs to be a change set selected all the time for an admin user, the default change set is selected until you have created and/or selected a change set of your own choosing this means your changes will be tracked against that default change set this is typically useful for changes you only want to make in that environment or for a place you can move your changes to if you do not want them captured in another change set you should not modify the default change set and you should never close it change track mode there are three modes in change sets that determines whether or not the selected change set to change into another mode, click on the left/right arrow around the mode's name, to get to the mode you want tracking configuration this is the default mode and this tracks configuration changes made tracking off this is not tracking anything a common use case is if you would like to make temporary changes that you do not want tracked by the selected change set tracking all changes this tracks all changes, i e all configuration changes but also non configuration data such as cis, locations, groups, etc this is especially helpful if you are building an integration, workflow or otherwise that relies on a certain group, user or other bit of data to operate configuring a table to be tracked by change sets as configuration to configure a table so that its records are tracked by change sets by default, you’ll need the following table properties set you can either set them during table creation under the advanced tab, or if the table is already created, find the table definition record for the table and go to its properties tab and find those two fields shown above configuring a many to many table (multi reference) to be tracked by change sets as configuration a multi reference field from one parent table to a child table, will result in a many to many relationship created example of this is user membership to groups if you need to migrate those relationship records as part of a change set, you will need to update the relationship’s property per the steps below find the relationship definition of the many to many relationship/multi reference or if the field is available visually on the parent record, find the field and right click on it then, left click on the “show definition” menu you will be presented with the “relationship definition” record there, you will need to update the properties under the relationship settings tab, that will look something like the below add a property “configuration data” and set the value to be true so that your relationship settings' properties will look like the following from this point on, any update on the multi reference field on a parent record, will be automatically captured into a change set, as long as the change set’s mode is set to “tracking configuration” reviewing changes viewing change set items prior to closing and exporting your change set, you may review the tracked changes (called change set items ) in case there are changes that were accidentally tracked example if you were testing a very specific configuration change that has nothing to do with your selected change set and you did not switch to “tracking off” mode to review the content, you can go to the change set record viewing the selected change set per the above section on “switching between change sets” below shows a sample list of change set items of a change set typical things that you want to look out for changed table, example is if your changes were purely about tables and fields and you saw a change on the “applicationproperty” table then you should view that particular change set item updated by, example if your changes should have been done only by yourself but you saw other user names there updated on date, example is your changes were all done several weeks prior and you have change set item updated yesterday id, in case you notice a record id there that you did not mean to update moving change set item to default change set if you need to move a change set item off a change set, you may do so by moving the item from your change set to the out of box “default” change set by right clicking on the change set item record on the list and left clicking on “move to ‘default’ change set' menu item think of default as a recycle bin of sorts for your changes, which you can recover if you want, but makes sure they are no longer in the change set you no longer want them in exporting changes closing a change set when you do not want your change set to track anymore changes, or you are ready to migrate, you may close that by clicking on the “close” button on the change set record exporting a change set to export your change set into a file that we can import into the target servicely environment, click on the “export” button on the change set record this will generate a xml file downloaded into your computer default file name will be changeset \<record id> xml example is changeset 22d5f93397e411ee8977067c31254f72 xml importing changes import a change set to import a change set, on your target servicely environment , navigate to administration > administrator tools > change sets on a list of change sets, click on the “import change set” button you will then see a pop up where you need to select your exported change set’s xml file from your source servicely environment once you have placed the xml file into the pop up, click on “import” once import is completed, you’ll be redirected onto the imported change set record you are now ready to have the change set to be verified verification the verification step of the imported change set is mandatory to ensure the integrity of the target servicely environment to do that, click on “verify” button on the imported change set record this will move the change set’s status either to “resolve conflicts” or “verified” resolving conflicts when there is at least one conflict, the change set status will move to “resolve conflicts” and you’ll see conflicts listed on the conflicts tab it is important to remember that not all conflicts will cause issues for example, sometimes conflicts will come up due to the fact that a record did not previously exist on the instance and you created and updated it in the same record example below you may go through the conflicts by checking what they are and the conflict types you can either accept the update will apply the update on the change set onto the target servicely environment ignore the update will not apply the update on the change set onto the target servicely environment you can either do the accept/update individually by right clicking on the conflict records such as below if you want to accept/ignore on all conflicts in one go, click the “accept all conflicts” or “ignore all conflicts” respectively apply changes once all conflicts have been resolved (either accepted or ignored), the change set record will move to the “verified” status the whole change set is now ready to be applied, i e all change set items that did not have conflicts + the ones with conflicts but accepted, will be applied onto the target servicely environment to apply the changes, click on the apply button once the change set has finished applying, the change set’s status will move to “applied” note that you cannot import the same change set to a servicely environment more than once therefore, if you need to make further changes, make a new change set in your source servicely environment and track your changes there you may then import that new change set onto the target servicely environment when ready examples of what should be captured although what you should and should not capture in a change set is typically dependent on the processes you have in place, it is suggested normally to use change sets every time scripts are changed and not used when data is changed (unless it is used and referenced from a script) this is typically because any data that may change in production by a non admin is something that naturally would not make sense to go via a non production, as these users typically would not have access to said non production please note that this list is not an exhaustive list and is simply a starter guide expected to use a change set for typically not used for a change set triggers ui event changes to the portal (excluding portal styles) script library form changes (noting that this often can get out of sync, so often is not done within a change set) new tables / fields permissions table record restrictions catalog items, questions and other related records catalog categories survey items/definitions/triggers menu items application definitions localisation changes (labels, hints) template reports (due to its focus on scripting) transform maps and data sources (if it is a scripted one) table operations workflows reclassification field maps inbound messages notifications schedules modals portal components jobs full text search application property users groups classifications configuration items companies departments reports dashboards integration tokens process records (i e incident, requests, changes, etc ) contracts time cards/time sheets templates scheduled templates knowledge bases and knowledge articles ldap servers attachments identity providers sla definitions there are often cases where you need to reference a specific one of these records to help with a new catalog item, integration or bit of functionality and in these cases it makes sense to capture that specific record in the change set this is due to the id potentially needing to be referenced, so creating it manually in different systems will cause an id mismatch there are often cases where you need to reference a specific one of these records to help with a new catalog item, integration or bit of functionality and in these cases it makes sense to capture that specific record in the change set this is due to the id potentially needing to be referenced, so creating it manually in different systems will cause an id mismatch