Script API
Introduction
This is a powerful scripting API that provides methods to simplify provisioning and executing other complex tasks in the repository manager. These APIs can be invoked from scripts that are published to the repository manager and executed within the application server.
More detailed documentation is available in the following topics:
Enabling Scripting
As of release 3.21.2, the Groovy scripting engine is disabled by default as a security best practice. For those upgrading, this affects Groovy scripts as used through the REST API and through scheduled tasks.
While keeping scripting disabled is a security best practice, you can enable it if necessary.
To enable all script features, edit $data-dir/etc/nexus.properties
, add the following on a new line, and restart Sonatype Nexus Repository:
nexus.scripts.allowCreation=true
Make sure the file is saved with an ending new line and with the original file permissions.
To temporarily allow adding/editing a script source, take the following steps:
Add the nexus.scripts.allowCreation=true property to $data-dir/etc/nexus.properties as described above and restart Sonatype Nexus Repository.
As a user with appropriate privileges, add/edit a script or task. Test the script if desired.
Remove or comment out (add a leading "#" character) the property that allowed script editing.
Restart Sonatype Nexus Repository.
Endpoints
Add Script
POST /service/rest/v1/script
This endpoint allows us to create a utility script within the repository manager.
As an example, let's create a simple script that simply logs "Hello, World!":
curl -u admin:admin123 -X POST --header 'Content-Type: application/json' \ http://localhost:8081/service/rest/v1/script \ -d @helloWorld.json
The JSON document we send includes the unique name of the script, the contents of the script itself, and the language type of the script (in this case groovy).
helloWorld.json
{ "name": "helloWorld", "content": "log.info('Hello, World!')", "type": "groovy" }
If you are using Windows and want to use Powershell to add a script you can use the following commands:
$bytes = [System.Text.Encoding]::UTF8.GetBytes("admin:admin123") $cred = [System.Convert]::ToBase64String($bytes) $uri = "http://localhost:8081/service/rest/v1/script" $jsonPath = "c:\test\helloWorld.json" Invoke-RestMethod -Uri $uri -Method POST -Headers @{"Authorization"="Basic $cred"} -ContentType "application/json" -InFile $jsonPath
List Scripts
GET /service/rest/v1/script
This endpoint allows us to get a listing of all the scripts currently defined in the repository manager.
curl -u admin:admin123 -X GET http://localhost:8081/service/rest/v1/script
Building on the example from above, we only have the one script that we just created:
Example Response
[ { "name" : "helloWorld", "content" : "log.info('Hello, World!')", "type" : "groovy" } ]
Get Script
GET /service/rest/v1/script/{name}
This endpoint allows us to get the details for an individual script by its name.
Let's get the details for the helloWorld script that we defined earlier:
curl -u admin:admin123 -X GET http://localhost:8081/service/rest/v1/script/helloWorld
Example Response
{ "name" : "helloWorld", "content" : "log.info('Hello, World!')", "type" : "groovy" }
Update Script
PUT /service/rest/v1/script/{name}
This endpoint allows us to update the contents of an existing script.
Let's update our script to log "Hello, Nexus!" instead of "Hello, World!":
curl -u admin:admin123 -X PUT --header 'Content-Type: application/json' \ http://localhost:8081/service/rest/v1/script/helloWorld \ -d @helloNexus.json
helloNexus.json
{ "name": "helloWorld", "content": "log.info('Hello, Nexus!')", "type": "groovy" }
Run Script
POST /service/rest/v1/script/{name}/run
This endpoint allows us to run a script that we have already defined in the repository manager.
Let's run our helloWorld script:
curl -u admin:admin123 -X POST --header 'Content-Type: text/plain' \ http://localhost:8081/service/rest/v1/script/helloWorld/run
The JSON response tells us which script ran and the returned result from the script:
Example Response
{ "name" : "helloWorld", "result" : "null" }
We should also see something like the following in the console log:
2018-01-22 16:28:55,495+0000 INFO [qtp74765809-267] admin org.sonatype.nexus.script.plugin.internal.rest.ScriptResource$$EnhancerByGuice$$99ce415 - Hello, Nexus!
Tip
To run a script, a user needs to have the nx-script-${script-name}-run privilege. A user with the nx-script-*-run privilege can run all scripts. Note that they will also need privileges assigned to them which allow them to perform the actions that the script does.
Delete Script
DELETE /service/rest/v1/script/{name}
This enpoint allows us to delete scripts once they are no longer needed.
Let's delete our helloWorld script:
curl -u admin:admin123 -X DELETE http://localhost:8081/service/rest/v1/script/helloWorld
A successfull deletion returns no content:
Example Response
HTTP/1.1 204 No Content Date: Mon, 22 Jan 2018 22:58:03 GMT ...