Overview
Common maintenance activities when running XL Deploy are adding, modifying, and removing items from its repository. This is especially the case for infrastructure and environment configuration items (CIs) that are not published to XL Deploy automatically in the way deployment packages usually are.
Here, we'll use curl to go through an example of the XL Deploy REST API calls you'll need to make such a scenario work, specifically:
- Creating a new CI
- Reading an existing CI from the repository
- Updating the properties of an existing CI
- Deleting a CI from the repository
Creating a new CI
Use POST /repository/ci/{ID:.*?} to create a new CI. Here, we'll create a new overthere.LocalHost CI with ID Infrastructure/my-new-ci.
Input:
curl -u<username>:<password> -X POST -H "Content-type:application/xml" http://<xl-deploy
-server>:<xl-deploy-port>/deployit/repository/ci/Infrastructure/my-new-ci -d@/tmp/read-ci.xml
Content of /tmp/read-ci.xml:
<overthere.LocalHost id="Infrastructure/my-new-ci">
<os>UNIX</os>
</overthere.LocalHost>
Output:
<overthere.LocalHost id="Infrastructure/my-new-ci" token="61cfc7c5-9ea5-4883-9a98
-ae721f678aaa">
<os>UNIX</os>
</overthere.LocalHost>
The description of the CI, as it was actually saved, is returned. This may differ from the input XML; that is, it may contain properties with default values that were not specified in the input.
If you want to create a CI that is linked to an artifact (although this is usually the case only for CIs in deployment packages), take a look at the version of the API call that takes a multipart ArtifactAndData parameter. An example would be:
Input:
curl -u<username>:<password>-X POST -H "Content-type:multipart/form-data"
http://<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Applications/
forDatabase/1.0/MySQL -F configurationItem=@/tmp/create_ci_with-data.xml -F
filename=sqlScripts.zip -F fileData=@/tmp/sqlScripts.zip
Content of /tmp/read-ci.xml:
<sql.SqlScripts id="Applications/forDatabase/1.0/MySQL" file="MySQL/sqlScripts.zip">
<tags />
<scanPlaceholders>true</scanPlaceholders>
</sql.SqlScripts>
Output:
<sql.SqlScripts id="Applications/forDatabase/1.0/MySQL" token="67dcd04b-6a71-40ef-a3ec
-de2543bcfc3c">
<tags/>
<scanPlaceholders>true</scanPlaceholders>
<placeholders/>
<checksum>c04b05d7f98f5b7c919233b3c819f28a7a05f585</checksum>
</sql.SqlScripts>
You can find the specific properties that the CI supports in the documentation of the appropriate plugin (for example, in the Remoting Plugin Manual for overthere.LocalHost). An easy way to get a sample of the XML for a certain type is to use the UI or CLI to create a dummy CI of that type and then use the REST API to read it.
Reading an existing CI from the repository
Use GET /repository/ci/{ID:.*?} to read an existing CI from the repository.
Input:
curl -u<username>:<password> http://<xl-deploy-server>:<xl-deploy-port>
/deployit/repository/ci/Infrastructure/my-new-ci
Output:
<overthere.LocalHost id="Infrastructure/my-new-ci" token="eb5cacc9-8beb-447f-8e12-
4756151f8308">
<os>UNIX</os>
</overthere.LocalHost>
We need to store the output of this call in a temporary location because we want to update this CI in the next call.
The token included in the return is a generated value that is used to prevent concurrent modifications to the repository. If you try to update an existing CI, the server will compare the value of the token you pass to the current value on the CI. If they are different, it means that the CI has been updated since you read the value, and the server will return a 409 error.
Updating the properties of an existing CI
Let's assume we saved the output of the previous call in /tmp/read-ci.xml. We can then modify any attributes we want to change in the file and use PUT /repository/ci/{ID:.*?} to update the CI in the repository.
Input:
curl -u<username>:<password> -X PUT -H "content-type:application/xml" http://
<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Infrastructure/my-new-ci
-d@/tmp/read-ci.xml
Content of /tmp/read-ci.xml:
<overthere.LocalHost id="Infrastructure/my-new-ci" token="eb5cacc9-8beb-447f-8e12-
4756151f8308">
<os>WINDOWS</os>
</overthere.LocalHost>
Output:
<overthere.LocalHost id="Infrastructure/vm1" token="bab17047-9614-48b6-a741-1081a8541b48">
<os>WINDOWS</os>
</overthere.LocalHost>
Again, take a look at the version of the command that takes a multipart ArtifactAndData parameter if you're looking to update the artifact associated with the CI.
Deleting a CI from the repository
We can use DELETE /repository/ci/{ID:.*?} to delete our CI from the repository.
curl -u<username>:<password> -X DELETE http://<xl-deploy-server>:<xl-deploy
-port>/deployit/repository/ci/Infrastructure/my-new-ci
Additional information
For more information on using the REST API with XL Deploy, please browse to the REST API reference on the Developer Docs portal and select your version
Comments
Please sign in to leave a comment.