Skip to main content

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:

  1. Add the nexus.scripts.allowCreation=true property to $data-dir/etc/nexus.properties as described above and restart Sonatype Nexus Repository.

  2. As a user with appropriate privileges, add/edit a script or task. Test the script if desired.

  3. Remove or comment out (add a leading "#" character) the property that allowed script editing.

  4. 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
...