|
| 1 | +# Program Package Development |
| 2 | +This program package guides you through how to develop |
| 3 | +programs for WPS Hub Deployment Services within a |
| 4 | +program package. |
| 5 | + |
| 6 | +Program packages are stored in git, and are edited using |
| 7 | +normal editors and a standard git client. The program package |
| 8 | +git repository can be hosted by the Hub itself, or it |
| 9 | +can he hosted on a site such as Github. |
| 10 | + |
| 11 | +When using program packages, the package becomes the unit |
| 12 | +of deployment. So all programs within a package are deployed |
| 13 | +together to an environment. |
| 14 | + |
| 15 | +## Package structure |
| 16 | +A package can be structured in any way you choose. Programs |
| 17 | +can be placed in directories for organisation if necessary. |
| 18 | +However, it is important to note that the complete git repository |
| 19 | +is deployed together. The package becomes the unit of deployment. |
| 20 | +So make sure that the git repository only contains resources |
| 21 | +that are necessary for deployment. It is not possible to deploy |
| 22 | +only part of a repository. |
| 23 | + |
| 24 | +In simple terms, if there is a file called "hello.sas" in the |
| 25 | +package, it can be invoked using a URL of `deployed-package-name/hello.sas`. |
| 26 | + |
| 27 | + |
| 28 | +## Package Descriptor File |
| 29 | +There is an optional file, `package.yaml` that can exist |
| 30 | +in the root directory of a package. This describes, amongst |
| 31 | +other things, the programs within the package that should be |
| 32 | +published to the directory. Note that publication of programs |
| 33 | +in the directory is not required for invocation. Programs can be |
| 34 | +invoked directly if the URL is known ('ex-directory' programs). |
| 35 | +Publication in the directory is necessary in order for the program |
| 36 | +to be invoked using an invocation interface such as the Excel plugin. |
| 37 | + |
| 38 | +### Syntax |
| 39 | +The package.yaml file is a YAML file with the following fields: |
| 40 | + |
| 41 | +| Field | Type | Description | |
| 42 | +| ----- | ---- | ----------- | |
| 43 | +| publishInDirectory | Array of string | A list of the relative paths to the programs to publish in the directory | |
| 44 | + |
| 45 | +## Program Descriptor |
| 46 | +In order to be able to invoke a program it is necessary to have a description of its interface and invocation options. This information is stored in the program descriptor that is associated with a program. |
| 47 | + |
| 48 | +The program descriptor is placed in a separate YAML file alongside the program source file. The program descriptor should have the same name as the program source file, with an additional ".yaml" extension. So for a program source file called "hello.sas", the program descriptor should be in a file called "hello.sas.yaml". |
| 49 | + |
| 50 | +Note that a program descriptor isn't strictly necessary. For a program that has no parameters, and uses all of the default execution options, no descriptor is required. In all but the simplest of cases though the descriptor is required. |
| 51 | + |
| 52 | +### Program Descriptor Syntax |
| 53 | +The descriptor is a YAML formatted file with the following base properties: |
| 54 | + |
| 55 | +| Field | Type | Description | |
| 56 | +| ----- | ---- | ----------- | |
| 57 | +| label | string | The label under which this program is published in the directory. This is only relevant if the program is included in the list of programs to be published within the package descriptor file. If not specified, the program's file name, without extension, is used. |
| 58 | +| description | string | A description of the program to place in the directory. This is only relevant if the program is included in the list of programs to be published within the package descriptor file. |
| 59 | +| categories | array of string | A list of categories under which the program will be listed in the directory, if it is to be published. |
| 60 | +| parameters | array of object | A list of the parameters for the program. |
| 61 | + |
| 62 | +#### SAS Language Programs |
| 63 | +In addition, for SAS language programs, the following properties can be specified: |
| 64 | + |
| 65 | +| Field | Type | Description | |
| 66 | +| ----- | ---- | ----------- | |
| 67 | +| resultType | string | One of the values `stream` or `dataset`. |
| 68 | +| resultContentType | string | The media type of the output in the case of `resultType` being set to `stream` |
| 69 | +| resultDatasetName | string | The name of the data set to be returned in the case of `resultType` being set to `dataset` |
| 70 | +| resultFormat | string | One of the values `json`, `csv` or `xml`. Determines how data sets are converted to text when generating the response. |
| 71 | +| parameterStyle | string | One of the values `macroVars` or `dataset`. Determines how parameters are passed into the program. |
| 72 | + |
| 73 | +These settings are described by way of the examples |
| 74 | + |
| 75 | +#### R Language Programs |
| 76 | +In addition, for R language programs, the following properties can be specified: |
| 77 | + |
| 78 | +| Field | Type | Description | |
| 79 | +| ----- | ---- | ----------- | |
| 80 | +| resultType | string | One of the values `stream`, `object` or `console`. |
| 81 | +| resultContentType | string | The media type of the output in the case of `resultType` being set to `stream` |
| 82 | +| resultObjectName | string | The name of the R object to be returned in the case of `resultType` being set to `object` |
| 83 | +| resultFormat | string | One of the values `json`, `csv`, `print` or `tab`. Determines how the result object is converted to text when generating the response. |
| 84 | +| parameterStyle | string | One of the values `macroVars` or `dataset`. Determines how parameters are passed into the program. |
| 85 | +| initText | string | A set of R program statements that are invoked once within the R runtime that will be used to invoke this program. |
| 86 | + |
| 87 | +These settings are described by way of the examples |
| 88 | + |
| 89 | +## Examples |
| 90 | +There are two sets of examples, one in the SAS language and one in the R language. |
| 91 | + |
| 92 | +* [SAS Language examples](sas/README.md) |
| 93 | +* [R Language examples](r/README.md) |
| 94 | + |
| 95 | + |
| 96 | + |
0 commit comments