Atomia Automation Server

Simple service description

39 views 1

Configuring the services the Atomia Automation Server can work with, the relations between them, and their limitations.

Overview

A service description has exactly one ([1..1]) simpleServiceList element. This element has no attributes.

The element simpleServiceList can have one or more ([1..*]) simpleService elements. Each of these elements represents one Simple Service.

<simpleService name="Name" friendlyName="FriendlyName" providingModule="ModuleName"  min="0" max="4294967296" hidden="true" noSave="true" />

Simple Service attributes:

  • name – Required attribute. Name of the simple service. Must be unique. The accepted value is any combination of alphanumeric characters.
  • friendlyName – Friendly name of the service. Accepted values are all alphanumeric and special characters except XML special characters.
  • providingModule – Name of the module that can provide and manage services on a resource. Although this property is not required for each simple service element, root simple services must have this property set. All child services are provisioned by the same module so there is no need to set this property for them. The accepted value is the full name of the provisioning module in the format: Namespace.ModuleName.
  • min – Minimum number of this service that can occur in a parent service. Accepted values are unsigned int. Default value is 0.
  • max – Maximum number of this service that can occur in a parent service. Accepted values are unsigned int. By default maximum number is unlimited.
  • hidden – If set to true, service will not be visible outside the Atomia Automation Server core. The accepted value is of boolean type. Default value is false.
  • noSave – If set to true, service is not saved in the Atomia Automation Server database. Control of this type of service is managed completely by modules. These types of services are called DirectProvisionedservices. The accepted value is of boolean type. Default value is false.

Simple service properties

Each simple service can have a maximum of one property list ([0..1]) containing properties that are needed for creating the service. The XML tag that describes this is propertyList:

             <simpleService name="Name" providingModule="ModuleName">
             <propertyList>
             <property name="PropertyNameForService" />
             <propertyList>
             <!-- ... -->
             </propertyList>
             </propertyList>
             </simpleService>

propertyList element does not have any specific attributes. It can appear zero or one ([0..1]) times per service.

propertyList element has a list of none or many ([0..*]) property elements.

Element property has the following attributes:

             <simpleService name="Name" providingModule="ModuleName">
             <propertyList>
             <property name="PropertyNameForService" friendlyName="PropertyFriendlyName" storeType="store" defaultValue="" key="false"  allowDefaultOverride="false" required="true" log="true" />
             <propertyList>
             </simpleService>
  • name – Required attribute. Property name. It must be unique per service. Accepted values are all alphanumeric characters.
  • friendlyName – Friendly name of the service property. Used to display the name of the property to the user. Accepted values are all alphanumeric and special characters except XML special characters.
  • storeType – Determines how property value should be stored. It could be stored in its original form, encrypted, or even not stored. Accepted values are: store, encrypt and noStore. Default value is store.
  • defaultValue – Property default value. Accepted values are all alphanumeric and special characters except XML special characters. If this value is set the user will not be asked for this property value.
  • key – Determine if this property is a key property for service. Service could have one or more key properties. If two services have the same values for key properties then we are considered to be the same service. It is used to determine if two logical services should point to the same physical service. Accepted values are of boolean type. Default value is false.
  • allowDefaultOverride – Tells whether it is possible to override the default value of the service property if it exists. Accepted values are of boolean type. The default value is false. This property is not counted unless defaultValue is set.
  • required – Tells whether this property is required. Value for service properties which has required set to true must be provided. Accepted values are of boolean type. Default value is false.
  • log – Tells whether this property’s value should be written to the Atomia Provisioning log. Accepted values are of boolean type. Default value is true. Also, if the value is false,  Atomia will not write the property in the audit logs and action trail logs.

Input value transformation

Transforms the input value of the service property as described in the inputValueTransformation element. Expressions used for describing transformation are Atomia Provisioning Element Transformations. Each service property can have ([0..1]) of these elements as child elements.

               <simpleService name="Name" providingModule="ModuleName">
               <propertyList>
               <property name="PropertyNameForService" >
               <inputValueTransformation>literal.+$Service::Property</inputValueTransformation>
               </property>
               <propertyList>
               </simpleService>

Service operations

Each simple service can have a maximum of one list ([0..1]) of service operations that can be called for that service. When called, these operations are executed on the specific instance of Atomia Provisioning service. XML tag that describes this is operationList :

             <simpleService name="Name" providingModule="ModuleName">
             ...
             <operationList>
             ...
             </operationList>
             ...
             </simpleService>

operationList element does not have any specific attributes. It can appear zero or one ([..1]) time per service. operationList element has a list of none or many ([0..*]) operation elements.

The element operation has the following attributes:

             <simpleService name="Name" providingModule="ModuleName">
             ...
             <operationList>
             <operation name="Start" />
             <operation name="Stop" />
             <operation name="Pause" />
             </operationList>
             ...
             </simpleService>
  • name – Name of service operation. It must be unique per service. Accepted values are alphanumeric characters.

Simple service child services

Each simple service can have zero or one list ([0..1]) of childSimpleServices. The XML tag that describes this is childSimpleServices:

             <simpleService name="ParentName" providingModule="ModuleName">
             <propertyList>
             <property name="PropertyNameForService" />
             </propertyList>
             <childSimpleServices>
             <simpleService name="ChildName" providingModule="ModuleName">
             </simpleService>
             </childSimpleServices>
             </simpleService>

There are no specific attributes for this element. Every simple service can have children which must be of type simple service. A simple service can have a recursive structure (for example simple service “Folder” can have child “Folder”). Example:

             <simpleService name="WebSite" providingModule="WebSiteModule">
             <childServiceList>
             <simpleService name="Folder">
             <propertyList>
             <param name="DirName" />
             </propertyList>
             <childServiceList>
             <simpleService name="Folder"></simpleService>
             </childServiceList>
             </simpleService>
             </childServiceList>
             </simpleService>

Action hooks

Each simple service can have zero or one list ([0..1]) of actionHooks element. This element has no attributes.

The element actionHooks can have zero or more ([0..*]) of onBeforeAddService or onSwitchService elements. These elements have the following attributes:

             <simpleService name="VirtualDir">
             ...
             <actionHooks>
             <onBeforeAddService type="Namespace.Type, Assembly" argument="Argument" />
             </actionHooks>
             </simpleService>

Action hooks contain logic that can be executed on different events which occur in the provisioning process. Currently, available events are onBeforeAddService and onSwitchService.

  • type – Required attribute. Full name of the type which represents an action hook. Accepted values are full names of the classes representing action hook.
  • argument – Required attribute. Action hook argument. Accepted values are alpha numeric characters.

Composite service description

The service description file can contain multiple composite services. Simple services are services that are provisioned on a single resource and are not dependent of other services. They serve as building blocks for composite services.

Composite services are services composed of one or many services, not necessarily provisioned on a single resource. We describe composite service using:

  • list of properties
  • list of possible child services (part services and part instances)
  • list of services that are initially added on composite service creation

Example of a composite service description:

             <complexService name="FtpSupport" friendlyName="FTP"
             systemUnique="true">
             <complexServicePropertyList>
             <complexServiceProperty name="FtpSupportProperty" />
             </complexServicePropertyList>
             <partList>
             <partService name="Storage" max="1" min="1">
             </partService>
             <partService name="FTP">
             <propertyTransformation>
             <simpleTransformer>
             <serviceProperty name="HomeDir">
             <expression>\#Instance(FtpStorageInstance).Resource.ServerName++#Instance(FtpStorageInstance)::Path</expression>
             </serviceProperty>
             </simpleTransformer>
             </propertyTransformation>
             </partService>
             <partServiceInstance name="FTPAccunt" condition="\#Instance(FtpStorageInstance).Resource.ServerName eq SomeValue" instanceName="FTPAcc">
             <propertyTransformation>
             <simpleTransformer>
             <serviceProperty name="Name">
             <expression>\#Instance(FtpStorageInstance).Resource.ServerName+_acc</expression>
             </serviceProperty>
             </simpleTransformer>
             </propertyTransformation>
             </partServiceInstance>
             </partList>
             <init>
             <add partName="Storage" instanceName="FtpStorageInstance" canDelete="false" canEdit="false">
             <initPropertyList>
             <propertyTransformation>
             <simpleTransformer>
             <serviceProperty name="Path">
             <expression>usersUserName</expression>
             </serviceProperty>
             </simpleTransformer>
             </propertyTransformation>
             </initPropertyList>
             </add>
             </init>
             </complexService>

Composite service element attributes:

  • name – Gives a name to the service. Must be unique. Required attribute. Accepted values are of any SimpleType.
  • friendlyName – Friendly name of the service. Attribute not required. Accepted values are of any SimpleType.
  • systemUnique – Accepted type – boolean. Default value false.

Composite services properties

A composite can have a list of properties. The list of properties is defined by:

               <complexServicePropertyList>
               <complexServiceProperty name="ZoneName" />
               <complexServiceProperty name="Subdomain" />
               <complexServiceProperty name="Port" />
               <complexServiceProperty name="ASPLocaleID" />
               <complexServiceProperty name="LoggingType" />
               </complexServicePropertyList>

The element complexServicePropertyList has no attributes.

Each property is defined by the element complexServiceProperty.

<complexServiceProperty name="ZoneName" friendlyName="PropertyFriendlyName" defaultValue="PropertyDefaultValue" store="true" key="false" />

Attributes are:

  • name – Composite service unique property name. Required attribute.
  • friendlyName – Composite service user-friendly property name. Optional attribute.
  • defaultValue – Default value for property. Accepted data type – string.
  • store – Determines if this property value will be stored in the database. Default attribute value – true. Accepted data type – boolean.
  • key – Optional. Default value – false. Accepted data type boolean. Declares property as a composite service key property.

Composite service child services

A composite service child service is defined either with the element partService or partServiceInstance. The relation between a composite child service and its parent service is whole-part. This means that a composite service is defined by its set of services.

               <partList>
               <partService name="partServiceName" min="" max="1" canAddSame="" equivalenceCriteriaParams="">
               </partService>
               <partServiceInstance name="FTPAccunt" condition="\#Instance(FtpStorageInstance).Resource.ServerName eq SomeValue" instanceName="FTPAcc">
               </partServiceInstance>
               </partList>

A composite service may have zero or one time ([0..1]) partList elements. The partList element has no attributes.

The partService attribute is used for describing the child service. partList must have one or more ([1..*]) partService elements.

<partService name="partServiceName" min="0" max="12323" canAddSame="true" equivalenceCriteriaParams=""></partService>

partService attributes are:

  • name – Name of the simple or complex service defined above. Required attribute. The accepted type is alphanumeric string.
  • min – Minimum number of service appearances in the parent. Optional attribute.
  • max – Maximum number of service appearances in the parent. Optional attribute.
  • canAddSame – Determines if a user can add the same service more than once (compares to other services in the same complex service instance). Default value true. Accepted data type – boolean. Optional attribute.
  • equivalenceCriteriaParams – List of properties name separated with “;” that defines what service properties must have the same value to be able to declare services as the same. Optional attribute.
  • condition – If set, holds expression that is used to check if certain part service type can be added. Optional attribute. Accepted data type – string. Expressions are Atomia Provisioning Element Transformations.
  • forcePropertiesUpdate – If this property is set system will schedule part service for update even if there are no changes to service properties. Useful when complex service property is expected to be changed after some other service property is updated by module or any other Automation Server plug-in. Optional attribute. Accepted data type – boolean. Default value – false.
  • deletePriority – Used to specify priority order for deletion. Parts with higher priority will be deleted first. Optional attribute. Accepted data type – uint. Default value – 0.

partService, if the part is of type of simple service, it can also have a child part list. This structure must match the simple service structure. A  partService that is a type of composite service defines its parts in the composite service definition.

Child service defined as partServiceInstance is added when a condition, described in condition attribute is met. Condition is evaluated whenever a service, involved in the condition, is being added, modified, or deleted. Once a condition value becomes false, all partServiceInstance, owners of the condition, will be deleted. partServiceInstance attributes are:

  • name – Name of the simple or complex service defined above. Required attribute. The accepted data type is alphanumeric string.
  • condition – If set, holds expression that is used to check if certain part service type can be added. Optional attribute. Accepted data type – string. Expressions are Atomia Provisioning Element Transformations.
  • instanceName – Instance name. Name used to distinguish this type of part service instance. The accepted data type is alphanumericstring.
  • deletePriority – Used to specify priority order for deletion. Parts with higher priority will be deleted first. Optional attribute. Accepted data type – uint. Default value – 0.

Composite service initialization

Composite service initialization consists of services that need to be initially added when the composite service is created. They are described with the init element.

               <init>
               <add partName="Storage" instanceName="StorageInstance" canDelete="false" canEdit="false">
               ...
               </add>
               </init>

The init element has no attributes. It always has one or more ([1..*]) add elements.

               <add partName="Storage" instanceName="StorageInstance" canDelete="false" canEdit="false" instanceName="partNameInstanceName">
               <initPropertyList>
               <propertyTransformation>
               <simpleTransformer>
               <serviceProperty name="Path">
               <expression>usersUserName</expression>
               </serviceProperty>
               </simpleTransformer>
               </propertyTransformation>
               </initPropertyList>
               </add>

The add element attributes are:

  • partName – Defines partService name. Required attribute. Accepted data type – string.
  • canDelete – Determines if this partService instance can be deleted. Optional attribute. Default value – true.
  • canEdit – Determines if this partService instance can be edited. Optional attribute. Default value – true.
  • instanceName – Used for later referencing of this instance by some other part in composite service initialization. Optional attribute. Accepted data type – string
  • condition – Defines condition which must be met in order to initially add part service. Expressions used for describing transformation are Atomia Provisioning Element Transformations. The default value is an empty string.

The add element can have zero or one ([0..1]) initPropertyList elements. It is used to initialize a list of properties for the service instance.

<initPropertyList/>

initPropertyList can have ([0..1]) initProperty elements. They are used to initialize service instance properties with fixed values, instead of assigning property values using property transformation.

<initProperty name="propertyName" value="propertyValue"/>

The initProperty value has the following attributes:

  • name – Property name. Required attribute.
  • value – Property value. Required attribute.

initPropertyList can have ([0..1]) propertyTransformation elements describing how a parent composite service property value will be transformed to this service property value.

               <propertyTransformation>
               <simpleTransformer>
               <serviceProperty name="Subdomain">
               <expression>$WindowsSite::Subdomain</expression>
               </serviceProperty>
               </simpleTransformer>
               </propertyTransformation>

propertyTransformation has no attributes.

propertyTransfromation must have one or more ([1.. ]) simpleTransformer elements that describe the transformation process. simpleTransformerdoes not have attributes but has one or more ([1.. ]) serviceProperty elements.

               <serviceProperty name="Subdomain">
               <expression>$WindowsSite::Subdomain</expression>

simpleTransformer is a property transformer. The transformation is defined with the element serviceProperty. It defines what service property value in the current service will be transformed. The expression element defines how it will be transformed.

               <complexServiceList>
               <complexService name="WebSite">
               <complexServicePropertyList>
               <complexServiceProperty name="Domain" />
               </complexServicePropertyList>
               <partList>
               <partService name="DnsZone">
               <propertyTransformation>
               <simpleTransformer>
               <serviceProperty name="Domain">
               <expression>www.+$WebSite::Domain</expression>
               </serviceProperty>
               </simpleTransformer>
               </propertyTransformation>
               </partService>
               </partList>
               </complexService>
               </complexServiceList>

serviceProperty describes the property value transformation for a specific property. The name attribute is required. The expression element defines an expression that will be used for the property value transformation.

               <serviceName>$<serviceName>::<paramName>+<text>!Instance(<instanceName>)::<paramName>
               !Instance(<instanceName>)::!Resource.<ResourceProperty>

Was this helpful?