Skip to end of metadata
Go to start of metadata

Table Of Contents

Overview

This document describes the APIs that are available for use by consultants and developers to customize the VDI workflows available in Visual Enterprise Generator 8.0 or later.

It covers the following areas:

  • The new SAP Python APIs added for use by Python scripts executed by Visual Enterprise Generator.
  • The VDI web service used to start and managed VDI workflow jobs.

It does not cover:

Applicable To
Visual Enterprise Generator 8.0 or later

 

Python API

Visual Enterprise Generator includes a Python interpreter that supports Python 2.7 syntax (IronPython). 

Python scripts can be executed by Visual Enterprise Generator inside the context of an operation inside a process. This provides a way to programmatically extend Visual Enterprise Generator when more advanced scenarios need to be supported; for example, special processing of complex XML documents, calling web services or calling SAP RFC functions on your ERP system.

There are two types of operations that support Python scripts:

In both cases, the operation has a parameter of the Python scriptblock type, which has a code sub-parameter that containing the Python source code as its value.

In addition to the Python standard functionality, additional SAP APIs are provided to the Python script in its scope to simplify integrating the script with the surrounding SAP 3D Visual Enterprise Generator process and the SAP 3D Visual Enterprise runtime environment. 

These SAP APIs provide functionality like passing data from the process into the script, and back from the script into the process, as well as connecting to external systems using HTTP, web services or SAP RFC calls, and performing simple scene traversals or modifications.

The Python standard library is only included in Visual Enterprise Generator 8.0 SP1 or later. Prior versions only include the functionality provided out of the box by IronPython.

 

Callback Operations

A callback operation is a pre-defined operation provided byVisual Enterprise Generator, which has a Python script parameter. This script parameter contains a Python script that defines one or more Python functions with well-known names and function arguments.

When the operation is executed, it will at its discretion call one or more of these Python functions, and pass through the arguments expected by the function.

For example, the VDI workflows have an operation that calls a Python function defined by the script, and the responsibility of this function is to provide a PDM identifier for a CAD object, given a set of function arguments.

Custom Scriptable Operations

A scriptable operation is a custom user-defined Visual Enterprise Generator operation with custom input and output parameters, and an associated Python script block that implements the operation’s functionality.

Within the Process Designer, the user can create a new operation of this type, and after dragging this new operation onto the process canvas, edit its Python script to do whatever is required to implement the custom operation.

See Appendix A: Creating a Scriptable Operation for more details on how to create one of these operations.

Custom SAP APIs

All custom SAP APIs are grouped into a Python namespace named sap which is available to all scripts running inside an Visual Enterprise Generator process context.

Within this namespace are additional sub-groupings by functionality.

sap.input_parameters

This is a Python dictionary containing all of the parameters defined in the Input pane of the Operation Editor, for a custom scriptable operation. Any values set by the containing process before the operation executes will be passed through in this dictionary. The keys in this dictionary correspond to the names of the defined input parameters.

sap.output_parameters

This is a Python dictionary in which the script can set the values for parameters defined in the Output pane of the Operation Editor, for a custom scriptable operation. Any values set by the script will be made available as output parameters of the scriptable operation in the containing process.

The keys in this dictionary should correspond to the names of the defined output parameters.

sap.settings

This object provides access to some general Visual Enterprise Generator server settings.

Properties
PropertyDescription
InstallationPathThe full path to the location where Visual Enterprise Generator is installed
SharePathThe full path to the Visual Enterprise Generator share
WorkspacePathThe full path to the Workspace folder within the Visual Enterprise Generator share
VersionA .NET Version object containing the Visual Enterprise Generator version. The returned object has Major, Minor, Revision and Build properties that contain integers for the respective components of the Visual Enterprise Generator version. It can also be converted to a string by calling the .ToString() method on this object.

sap.log

The object sap.log provides the ability to log messages to the task log for a Visual Enterprise Generator process.

Methods
MethodDescription
debug(message)

Logs a message of severity Debug to the task log. Message will only be visible if trace logging is turned on in Visual Enterprise Generator configuration.

ArgumentDescription

message­

A string containing the message to log
info(message)

Logs a message of severity Info to the task log. Message will only be visible if informational logging is turned on in Visual Enterprise Generator configuration.

ArgumentDescription
message­A string containing the message to log
warning(message)

Logs a message of severity Warning to the task log. Message will only be visible if warning logging is turned on in Visual Enterprise Generator configuration.

ArgumentDescription
message­A string containing the message to log
error(message)

Logs a message of severity Error to the task log.

ArgumentDescription
message­A string containing the message to log
Example
sap.log.debug('trace message')
sap.log.info('informational message')
sap.log.warning('warning message')
sap.log.error('error message')

 

sap.jobreport

The object sap.jobreport provides the ability to add entries to the job report for the currently executing job, to allow customizations using Python to surface information to end-users. This is the job report seen in Visual Enterprise Generator Administrator or when using the VEG_JOBMONITOR transaction.

Methods

Each of these messages creates an entry in the job report. The type of the entry dictates which icon is used in the job report for the entry.

The method also returns an object that can be used to create child items for that object. For example, calling the Info() method on the object returned by the Assembly() method, will result in an Assembly object in the job report with an Info message as a child item.

MethodDescription
Part(name)

Adds an object of type Part to the job report.

ArgumentDescription
nameA string containing the name of the part
Return Value
A builder object that can be used to add child items to the part
Assembly(name)

Adds an object of type Assembly to the job report.

ArgumentDescription
nameA string containing the name of the assembly
Return Value
A builder object that can be used to add child items to the assembly
Asset(name)

Adds an object of type Asset to the job report.

ArgumentDescription
nameA string containing the name of the asset
Return Value
A builder object that can be used to add child items to the asset
File(name)

Adds an object of type File to the job report.

ArgumentDescription
nameA string containing the name of the file
Return Value
A builder object that can be used to add child items to the file
Folder(name)

Adds an object of type Folder to the job report.

ArgumentDescription
nameA string containing the name of the folder
Return Value
A builder object that can be used to add child items to the folder
Info(messageText)

Adds a message of type Info to the job report.

Argument 
messageTextA string containing the message text
Return Value
A builder object that can be used to add child items to the message
Warning(messageText)

Adds a message of type Warning to the job report.

ArgumentDescription
messageTextA string containing the message text
Return Value
A builder object that can be used to add child items to the message
Error(messageText)

Adds a message of type Error to the job report.

ArgumentDescription
messageTextA string containing the message text
Return Value
A builder object that can be used to add child items to the message
Example
assembly = sap.jobreport.Assembly('TopLevelAssembly')
part1 = assembly.Part('Part1')
part2 = assembly.Part('Part2')
folder = sap.jobreport.Folder('Folder 1')
folder.File('File 1')
folder.Info('Informational Message')

 

sap.jobresult

The object sap.jobresult provides the ability to add entries to the job results for the currently executing job. Job results are categorized name-value pairs with well-known names, that can be retrieved by external systems to determine additional information about job. An example of a result could be the DIR of a document created in the SAP DMS.

Job results differ from the job report in that they are intended for consumption by automated systems and not intended for human consumption directly.

Results added in this way can be retrieved by calling the JobGetResult() method of the VDI web service API.

The job result category named SAP is reserved for use by SAP, and should not be used to avoid the potential for naming collisions.

Methods
MethodDescription
Add(name, value)

Adds a job result. No check for existing results is performed.

ArgumentDescription
nameThe name of the result.
valueThe value of the result
Add(category, name, value)

Adds a job result. No check for existing results is performed.

ArgumentDescription
categoryThe category of the result, can be used as a grouping field.
nameThe name of the result.
valueThe value of the result.
Add(category, path, name, value)

Adds a job result. No check for existing results is performed.

ArgumentDescription
categoryThe category of the result, can be used as a grouping field.
pathThe path of the result, can be used as a sub-grouping field within a category
nameThe name of the result
valueThe value of the result
Update(name, value)

Updates a job result. If a result already exists with the specified name, its value will be overwritten.

ArgumentDescription
nameThe name of the result
valueThe value of the result
Update(category, name, value)

Updates a job result. If a result already exists with the specified name, its value will be overwritten.

ArgumentDescription
categoryThe category of the result
nameThe name of the result
valueThe value of the result


Update(category, path, name, value)

Updates a job result. If a result already exists with the specified name, its value will be overwritten.

ArgumentDescription
categoryThe category of the result, can be used as a grouping field.
pathThe path of the result, can be used as a sub-grouping field within a category
nameThe name of the result
valueThe value of the result


 

Example
sap.jobresult.Add('Key1', 'Value1')
sap.jobresult.Update('SAP', 'Document/10002123/VED/000/00', 'MaterialID', '123')

 

 

sap.authentication

The object sap.authentication provides the ability to configure the authentication method that will be used by all subsequent HTTP, RFC or web-service calls. This authentication method will be in place until another sap.authentication call is made, or the script terminates.

It supports the following authentication methods:

  • Basic username/password authentication
  • X.509 client certificate authentication
Methods
MethodDescription
WithUser(userName, password, [domain])

Configures the script to use basic username/password authentication for subsequent external calls.

ArgumentDescription
userNameA string containing the user name to use
passwordA string containing the password to use
domainAn optional string containing the domain for authentication

This method should not be used in production environments, as the password would not be stored securely, but would be present in the script source code itself. Instead, it is recommended that the WithERPUser() method be used instead, as it stores credentials using strong encryption in a secure location.

WithERPUser(projectName)

Configures the script to use basic username/password authentication using the credentials associated with a Visual Enterprise Generator project. This is the recommended way to set up basic username/password authentication as the credentials are stored, encrypted, in a secure location and not in the script source code.

ArgumentDescription
projectNameA string containing the name of the Visual Enterprise Generator project that has an associated user. The user association can be created in the Visual Enterprise Generator Administration tool, in the User Names and Passwords section of the SAP Integration tab.
WithCertificateFromFile(filename, [password])

Configures the script to use X.509 client certificate authentication, using a certificate loaded from a disk file.

ArgumentDescription
filenameThe path to the X.509 certificate file, in a format supported by the .NET X509Certificate2 class.
passwordAn optional string containing the password for the certificate, if the certificate file is password protected. It is recommended to use file system permissions to secure the certificate file as well.

It is not recommended to use this method in production environments. Instead, WithCertificatesFromStore() should be used, as it will use the Windows certificate store, which is protected by the operating system.

WithCertificatesFromStore()Configures the script to use X.509 client certificates stored in the certificate store of the Visual Enterprise Generator service user account. For example, if Visual Enterprise Generator is running as the DOMAIN\VEGUser user, the certificate should be stored in that user’s Windows certificate store. This is the recommended way to set up X.509 client certificate authentication, as the certificate is stored in a secure area protected by the operating system.
UserName(jobId)

Returns the user name used for authentication, for a specific Visual Enterprise Generator job.

ArgumentDescription
jobIdThe job ID to look up the credentials for.
ConnectionName(jobId)

Returns the ERP connection name used for authentication, for a specific Visual Enterprise Generator job.

ArgumentDescription
jobIdThe job ID to look up the connection name for.
Example
sap.authentication.WithUser('username', 'secret')
sap.authentication.WithERPUser('CustomProjectName')
sap.authentication.WithCertificateFromFile('c:\test.cer')
sap.authentication.WithCertificatesFromStore()
sap.authentication.UserName(sap.jobid)
sap.authentication.ConnectionName(sap.jobid)


sap.connection

The object sap.connection provides the ability to configure the proxy server that will be used for subsequent HTTP calls (raw HTTP as well as web services), to allow for performing these types of calls in environments where proxy servers are required for security reasons.

Methods
MethodDescription
ProxyServer(url)

Specifies the proxy server that should be used.

ArgumentDescription
urlThe URL to the proxy server, including port if required; for example, http://proxy:8080/
ProxyUser(userName, password, [domain])

Sets the credentials to use if the proxy server requires authentication.

ArgumentDescription
userNameThe user name with which to authenticate.
passwordThe password with which to authenticate.
domainAn optional string containing the name in which the user exists.


Example
sap.connection.ProxyServer('http://proxy:8080/')
sap.connection.ProxyUser('username', 'secret')


sap.http

 

The object sap.http provides the ability to make HTTP requests, like GET or POST requests, with helpers to simplify downloading and uploading files.

Properties
PropertyDescription
ResponseHeadersContains all of the response headers from the most recent HTTP GET or POST request.
Methods
MethodDescription
Get(uri)

Performs an HTTP GET request.

ArgumentDescription
uriThe URL to perform an HTTP GET request for
Return Value
Returns a string containing the HTTP response body
GetBuffer(uri)

Performs an HTTP GET request.

ArgumentDescription
uriThe URL to perform an HTTP GET request for
Return Value
Returns a .NET byte array containing the response body. Useful if the raw binary data is needed.


GetFile(uri, targetFileName)

Performs an HTTP GET, writing the response to a local disk file.

ArgumentDescription
uriThe URL to perform an HTTP GET request for
targetFileNameThe path to the file on disk where the data should be written
Post(uri, data)

Performs an HTTP POST request.

ArgumentDescription
uriThe URL to perform an HTTP POST request to
dataA string containing the data to use as the body of the POST request
PostBuffer(uri, data)

Performs an HTTP POST request.

ArgumentDescription
uriThe URL to perform an HTTP POST request to
dataA .NET byte array containing the data to use as the body of the POST request.


PostFile(uri, filePath)

Performs an HTTP POST request.

ArgumentDescription
uriThe URL to perform an HTTP POST request to
filePathThe name of the file containing the data that will be used as the body of the POST request
Example
html = sap.http.Get('http://www.google.com')
buffer = sap.http.GetBuffer('http://server.com/data')
sap.http.GetFile('http://server/file.zip', 'c:\\temp\\file.zip')
sap.http.Post('http://server/api/Login', '<login username="xx" password="yy" />')
sap.http.PostBuffer('http://server/api/Login', buffer)
sap.http.PostFile('http://server/api/FileUpload', 'c:\\file.zip')

The version of IronPython distributed with Visual Enterprise Generator includes support for parsing JSON, since this was added to Python 2.6.

Use the json module and the json.dumps and json.loads functions for this purpose.


sap.webservice

The object sap.webservice provides the ability to connect to any external SOAP web services for which the WSDL is available. It is implemented by using the standard .NET support for consuming web services (it uses the same mechanism to generate web service proxy classes as the wsdl.exe tool provided by Microsoft) .

Methods
MethodDescription
Create(wsdlPathOrUrl, [endpointUri])

Creates a proxy object that can be used to invoke all of the methods defined in the WSDL. If proxy objects have already been generated for the WSDL (determined by using the wsdlPathOrUrl argument as a key), they will be re-used.

ArgumentDescription
wsdlPathOrUrlThe path to the local file containing WSDL, or the URL of a location from where the WSDL can be downloaded. Should the WSDL require authentication or proxy server configuration to download, use the appropriate methods on sap.authentication or sap.connection before you call Create().
endpointUriAn optional string containing the URL that should be used to connect to the web service (instead of the URL specified in the WSDL, if any).
Return Value

Returns a proxy object containing invokable methods for all of the operations described by the WSDL.

All data types defined by the WSDL will also be automatically imported into the script scope by the Create() call, this is important to note if you have naming collisions in your script.

Remove(wsdlPathOrUrl)

Removes any proxy objects that may have been generated for a specific WSDL file or URL.

This should only to be used if the WSDL at a particular URL has changed, or the performance benefits of generated proxy caching will not be realized.


Examples
wsdl_path = Path.Combine(sap.settings.InstallationPath, '~WSDL', 'DOC_3I_DOCFILELINKINFORMATION_OUT.wsdl')

# this creates a proxy object for the web service
docinfo_service = sap.webservice.Create(wsdl_path)

# this calls the web service
response = docinfo_service.ECC_GetDocUrlByFileId(request)


sap.rfc

 

The object sap.rfc provides the ability to make calls to SAP systems using the RFC protocol, which allows for the majority of remotely accessible SAP function modules to be executed from  Visual Enterprise Generator.

 

It does this by providing access to the native RFC interface provided by the SAP .NET Connector v3.0, but taking responsibility for authentication and any other pre-configuration of the .NET connector objects on your behalf.

Methods
MethodDescription
GetDestination()

Creates an RfcDestination object for communicating with the SAP system associated with the current job, using the authentication and connection information associated with the current job. If the current job does not have these two pieces of information associated with it, the GetDestinationForConnection() method should be used instead.

Return Value
Returns a connected .NET Connector RfcDestination object that can be used to communicate with the remote SAP system.
GetDestinationForConnection(name)

Creates an RfcDestination object for communicating with the specified SAP system.

ArgumentDescription
nameThe name of the SAP system connection, as configured by the Visual Enterprise Generator Administration application in the Connections section of the SAP Integration tab. If the remote system requires authentication, and there is no authentication context associated with the current job, the sap.authentication methods should be used to configure the SAP system user to use before calling GetDestinationForConnection().
Return Value
Returns a connected .NET Connector RfcDestination object that can be used to communicate with the remote SAP system.

 

Example
dest = sap.rfc.GetDestination()

# Example of specifying custom credentials, if the current job has no associated authentication
# context:
#
# sap.authentication.WithERPUser('LOOKUPKEY')
# dest = sap.rfc.GetDestinationForConnection('CONNECTION')

server_id = str(sap.input_parameters['vegInstanceId'])
job_id = str(sap.input_parameters['vegJobIdentifier'])

repo = dest.Repository
func = repo.CreateFunction("VEG_SRV_RESET_LOCK")
rowStructure = repo.GetStructureMetadata("DMS_VEG_S_CAD_DATA").CreateStructure()
rowStructure.SetValue("PROSERVER", server_id)
rowStructure.SetValue("PROCONTEXT", job_id)
input = func.GetTable("IT_DMS_VEG_CAD_DATA")
input.Append(rowStructure)
func.Invoke(dest)
output = func.GetTable("ET_MESSAGE")
for message in output:
  number = message.GetString("NUMBER")
  text = message.GetString("MESSAGE")
  type = message.GetString("TYPE")
  if type == "S" or type == "I":
    sap.log.info("ERP locks released successfully: %s" % text)
  elif type == "W":
    sap.log.warning("ERP locks released, with warning: %s" % text)
  else:
    sap.log.error("ERP lock release encountered errors: %s" % text)

 

sap.graphics.events

The object sap.graphics.events provides access to information about 3D processing events, which are events that occur when loading or saving 3D data, or when performing other types of scene manipulations.

Methods
MethodDescription
GetChronologicalEvents()

Gets a list of processing events that have occurred, in chronological order, since the process began executing or the last time ClearEvents() was called.

Return Value
A sequence of GraphicsProcessingEvent objects for each event that has occurred
GetEventsWithIds(ids)

Gets a list of processing events that have occurred, filtered by a set of well-known event IDs

ArgumentDescription
idsA sequence of one or more integer event IDs used to filter the returned events
Return Value
A sequence of GraphicsProcessingEvent objects for each event that has occurred, and has an ID that exists within the list of IDs specified as an argument.
ClearEvents()Clears the list of processing events. All subsequent calls to GetChronologicalEvents() or GetEventsWithIds() will only return events that have occurred after this call.
ContainsEventWithId(id)

Checks whether an event with an event ID has occurred.

ArgumentDescription
idThe ID of the event to check
Return Value
A Boolean value of true if the event has occurred, false otherwise.


sap.graphics.factory

This object provides read and write access to elements in an open graphics scene. The scene can be opened with the go_scene_open operation. Any Python script that uses the graphics factory has to be in the subtree of this operation in the Visual Enterprise Generator process, and not after it.

Example

vme_ExtractMetadata is a script that uses the sap.graphics.factory object.

In the documentation below, the return values are often specified as .NET interface names. The name can be looked up in subsequent sections, where all the properties of the respective interface are listed.

Although the Return Value can be documented as "Sequence of ..." it is not strictly a sequence in terms of Python. It is in fact an IEnumerable<T> from the underlying .NET implementation and therefore cannot be indexed like [i] or sliced like [a:b]. It first has to be turned into a proper Python sequence using the list() or tuple() functions before indexing or slicing can be applied.

first_bom = scene.Boms[0]        # NOT correct 
first_bom = list(scene.Boms)[0]  # correct
last_bom = list(scene.Boms)[-1]  # correct
Properties
PropertyDescription
ActiveSceneReaderGets an object that is the entry point to the 3D scene for the purpose of reading only
ActiveSceneManagerGets an object that is the entry point to the 3D scene for the purpose of reading and modifying certain types of elements in the scene
Examples
readonly_scene = sap.graphics.factory.ActiveSceneReader
writable_scene = sap.graphics.factory.ActiveSceneManager

ActiveSceneReader

This object provides read access to elements in the 3D scene.

Properties
PropertyDescription
Boms

Retrieves all the BOMs in the scene.

CurrentBom

Retrieves the currently active BOM.

HasAssemblyHierarchy Indicates whether the current scene has assembly (instance-reference) hierarchy.
NumberOfFaces

Gets the number of faces the current scene has.

NumberOfVertices

Gets the number of vertices the current scene has.

Procedures

Retrieves the procedures in the scene. A procedure has multiple steps.

Portfolios

Retrieves the sequence of portfolios.

RootNodes

Sequence of public root nodes of the current BOM. Equivalent to: scene.CurrentBom.RootNodes.

RootNodesIncludingInternal

Sequence of all root nodes of the current BOM.

Equivalent to: scene.CurrentBom.RootNodesIncludingInternal

SourceFilePathReturns a string containing the path of the source file (the loaded file).
Example
scene = sap.graphics.factory.ActiveSceneReader
for bom in scene.Boms:
  sap.log.info(bom.Name)
  first_portfolio = list(scene.Portfolios)[0]
  sap.log.info("file={}".format(scene.SourceFilePath))

 

IMetadataReader

The objects returned from the scene properties above all implement the IMetadataReader interface. This means that two properties can be accessed for all these objects: MetadataValues and ReservedInternalMetadataValues. The exception is the SourceFilePath property which returns a string.

An IMetadataReader provides access to a sequence metadata values, which implements the IMetadataValue interface.I

Include the following line at the top of the script to make the metadata objects accessible:

from SAP.VE.Generator.Graphics.Wrappers.Metadata import IMetadataValue 

Properties
PropertyDescription
MetadataValuesSequence of public metadata values
ReservedInternalMetadataValues

Sequence of internal metadata values.

SAP reserves the right to add or remove internal metadata values at its discretion, it is not recommended that you write any business logic that depends on internal metadata values.

Example

The example below defines a generator that takes into account that a metadata value can be a collection of metadata values, and returns them recursively.

def expand(metadata_values):
  for mdv in metadata_values:
    if isinstance(mdv.Value, IEnumerable[IMetadataValue]): 
      for submdv in expand(mdv.Value):
        yield submdv
    else:
      yield mdv
  for mdv in expand(scene.CurrentBom.Metadata.MetadataValues):
    sap.log.info("{} {} {}".format(mdv.CategoryName, mdv.KeyName, mdv.Value))

IMetadataValue

The classes that implement this interface all have a CategoryName, KeyName, and Private property. In addition, there is a Value property; the data type of this property depends on the type of the metadata value.

PropertyDescription
CategoryNameA string containing the name of the category to which the metadata belongs
KeyNameA string containing the name of the metadata value
PrivateA boolean specifying whether or not this is a private metadata field
Value

The metadata value, its type can be one of the following:

  • string
  • double precision floating point
  • 64 bit signed integer
  • boolean
  • .NET DateTime structure
  • A sequence of IMetadataValue
Example

The following example returns the type of the metadata as string, but does not account for collection types. To test for a metadata value that is collection check for instance of IEnumerable[IMetadataValue].

def value_type(value):
  t = type(value)
  if t == str: return 'String'
  if t == int or t == System.Int64: return 'Integer'
  if t == float: return 'Real'
  if t == bool: return 'Boolean'
  if t == DateTime: return 'DateTime'
  if isinstance(value, IMatrixReader): return 'Matrix'
    raise Exception("Unsupported metadata type {} for value={}".format(t, value))

 

ISceneMemberReader

This interface is inherited by: ISceneReader, IBomReader, INodeReader, IObjectReader, IProcedureReader, IStepReader, IPortfolioReader, and IModelViewReader. It defines three properties that are common to all of these interfaces.

Properties
PropertyDescription
Handle

A 64-bit integer containing the internal identifier of the graphics element, unique with in the scene. Two objects with the same handle value are effectively the same object.

NameA string containing the name of the scene member
Metadata

If the scene has any metadata, an IMetadataReader is returned by this property. If no metadata, None is returned.

Example
metadata = scene.CurrentBom.Metadata.MetadataValues

 

IBomReader

This interface defines read access to a BOM object.

Properties
PropertyDescription
NumberOfFaces

Gets the number of faces the current bom has.

NumberOfVertices

Gets the number of vertices the current bom has.

RootNodes

Sequence of public root nodes of this BOM

RootNodesIncludingInternal

Sequence of all root nodes of this BOM, including internal nodes (e.g. camera objects)

 

Example
nodes = scene.CurrentBom.RootNodes
for node in nodes:
  sap.log.info("node: {}".format(node.Name))

 

IProcedureReader

This interface defines read access to procedure metadata and procedure steps.

Properties
PropertyDescription
StepsA sequence containing the steps of the procedure, as IStepReader instances.
Example
for step in procedure.Steps:
  sap.log.info("{}: {}".format(step.Name, step.Description))

 

IStepReader

This interface defines read access to procedure step description and metadata.

Properties
PropertyDescription
AssignmentsA sequence containing all of the assignments in the step, as IAssignmentReader instances
DescriptionA string containing the step text
TargetBom

An IBomReader instance representing the BOM that contains the assignment's nodes

VisibleNodesThe visible nodes in the TargetBom that are selected as part of the assignment, as INodeReader instances
Example
scene = sap.graphics.factory.ActiveSceneReader
for proc in scene.Procedures:
  sap.log.info(proc.Name)
  for s in proc.Steps:
    sap.log.info(" '{}'; '{}': '{}'".format(s.TargetBom.Name, s.Name, s.Description))
    for vn in s.VisibleNodes:
      sap.log.info(" Node={}".format(vn.Name))

 

IAssignmentReader

This interface defines  read access to an assignment object.

Unlike most other interfaces listed here the IAssignmentReader does not inherit the properties from ISceneMemberReader, so no Node, Handle and Metadata can be addressed through this interface.

Properties
PropertyDescription
AssignedNodesA sequence of INodeReader objects representing the nodes assigned to the step
AssignmentTypeA string indicating the type of assignment
Example

Prints the hierarchy of procedures, steps, assignments and nodes.

scene = sap.graphics.factory.ActiveSceneReader
for proc in scene.Procedures:
  sap.log.info(proc.Name)
  for step in proc.Steps:
    sap.log.info(" step={}".format(step.Name))
    for asn in step.Assignments:
      if asn.AssignedNodes:
        sap.log.info("    type={}".format(asn.AssignmentType))
        for node in asn.AssignedNodes:
          sap.log.info("      node={}".format(node.Name))

 

INodeReader

This interface defines read access a scene node object.

Properties
PropertyDescription
BoundingBoxA IBoundingBox representing two vectors that define the bounding box of the node.
ChildrenA sequence of INodeReader containing the child nodes of this node, if any.
ClosedA boolean value specifying whether or not this node is a closed node (child hierarchy hidden).
Identifiers

A sequence of IIdentifier containing VE identifiers associated with node.

MarkedA boolean value specifying whether or not this node has been marked.
NumberOfFaces

Gets the number of faces the current node has.

NumberOfVertices

Gets the number of vertices the current node has.

ObjectAn IObjectReader representing the the underlying object associated with this node. For example, a polygonal mesh object.
ObjectMatrixAn IMatrixReader defining the position of an object instance. For example, two nodes can refer to the same mesh object, but each position is an instance of that object at a different position in the scene.
ParentRelativeMatrix

An IMatrixReader defining the node's position relative to its parent node.

PMIA boolean specifying whether or not the object contains any attached Product Manufacturing Information.
Private

A boolean specifying whether or not this node is a private node.

Private nodes are used for internal purposes. Modifying or building business logic depending on them is not supported, and SAP reserves the right to remove them in future, or change their semantics, at any time, without notice.

Selected

A boolean indicating whether or not the node is currently part of the active selection, if any.

Visible

A boolean indicating whether or not the node is currently visible.

WorldMatrixAn IMatrixReader containing the position of the node relative to the world.

 

Example

The function below logs some node information. It checks whether the node.Object exists, and logs the handle of the object. Multiple nodes can point to the same underlying scene object.

def node_info(node):
  sap.log.info ("'{}' obj={} cls={} mark={} pmi={} pr={} sel={} vis={}".format(
    node.Name,
 (node.Object.Handle if node.Object else "N/A"),
    node.Closed,
    node.Marked,
    node.PMI,
    node.Private,
    node.Selected,
    node.Visible))

 

IIdentifier

Represents VE identifier

Properties
PropertyDescription
Fields

A sequence of IIdentifierField containing the fields associated with the identifier.

SourceString value representing source of the identifier.

Type

String value representing the type of the identifier.

IIdentifierField

Represents VE identifier field

Properties
PropertyDescription
NameString value representing name of the identifier field.

Value

String value representing the value of the identifier field.

IObjectReader

This interface defines read access to a graphics object.

Properties
PropertyDescription
IsRenderable A boolean indicating whether or not the object is renderable.
Type

An enumeration of type ObjectType. The following values are possible:

  • Mesh
  • Sprite
  • Procedural
  • Camera
  • Internal
Example
if node.Object and node.Object.Type == ObjectType.Mesh:
  sap.log.info("this object is a mesh")

 

IPortfolioReader

This interface defines provides read access to the portfolio object in a scene. A portfolio has modelviews.

Properties
PropertyDescription
ModelviewsA sequence of IModelViewReader containing the modelviews in a portfolio

 

Example
portfolios = sap.graphics.factory.ActiveSceneReader.Portfolios
modelviews = list(portfolios)[0].Modelviews

 

IModelViewReader

This object provides read access to a model view.

Properties
PropertyDescription
TargetBom

An IBomReader representing the BOM that contains the nodes that belong to the model view

VisibleNodesA sequence of INodeReader instances representing the nodes that belong to the model view.
Example

Prints all nodes of all modelviews of all portfolios in a scene.

scene = sap.graphics.factory.ActiveSceneReader
for pf in scene.Portfolios:
  sap.log.info(pf.Name)
  for mv in pf.Modelviews:
    sap.log.info("  " + mv.Name)
    for vn in mv.VisibleNodes:
      sap.log.info("    " + vn.Name)

 

IMatrixReader

This interface defines read access to a transformation matrix (object, parent-relative or world).

Properties
PropertyDescription
AxisXAn IVector3DReader representing the X axis vector of the matrix
AxisYAn IVector3DReader representing the Y axis vector of the matrix
AxisZAn IVector3DReader representing the Z axis vector of the matrix
Data

A two-dimensional 4x4 floating point array containing the transformation matrix data for the axes (x,y.z), location (t) and a scale factor.

The data is laid out as follows:

x1 x2 x3 0

y1 y2 y3 0

z1 z2 z3 0

t1 t2 t3 scale

IsIdentityA boolean value indicating if this matrix is mathematically an Identity matrix.
LocationAn I3dVectorReader representing the location component of the matrix
ScaleA floating point value representing the scale of the object
String12The transformation matrix represented in String12 format: string composed of 12 numbers in flat array.
String16The transformation matrix represented in String16 format: string composed of 16 numbers in flat array.
Example

This function converts a matrix to a string containing its space separated values.

def matrix_to_string(m):
  values = []
  for axis in (m.AxisX, m.AxisY, m.AxisZ, m.Location):
    values.extend(axis.Data)
    values.append(m.Scale)
  return " ".join(str(v) for v in values)

 

IVector3DReader

This interface provides read access to the vector components.

Properties
PropertyDescription
DataAn array of 3 floating point numbers, in the order x, y, z
XA floating point value for the x component of the vector
YA floating point value for the y component of the vector
ZA floating point value for the z component of the vector
Example

The following returns a matrix as a string of the format "[[xx,xy,xz], [yx,yy,yz], [zx,zy,zz], [lx,ly,lz]]"

def vector(ax):
  return "[{}, {}, {}]".format(ax.X, ax.Y, ax.Z)


def matrix_string(m):
  s = ", ".join(vector(ax) for ax in (m.AxisX, m.AxisY, m.AxisZ, m.Location))
  return  "[" + s + "]"

print matrix_string(some_node.ObjectMatrix)



IBoundingBox

This interface provides read access to the bounding box components.

Properties
PropertyDescription
MinimumAn IVector3DReader representing the first vector defining the bounding box
MaximumAn IVector3DReader representing the second vector defining the bounding box
Example

The following returns Minimum and Maximum vectors components of Bounding Box.

def iteratenodes(node):
    box = node.BoundingBox
    vector = box.Minimum
    sap.log.debug("MSG: node:'%s' Minimum X:'%s', Y:'%s', Z:'%s', " % (node.Name, vector.X, vector.Y, vector.Z))
    vector = box.Maximum
    sap.log.debug("MSG: node:'%s' Maximum X:'%s', Y:'%s', Z:'%s', " % (node.Name, vector.X, vector.Y, vector.Z))
    for child in node.Children:
        iteratenodes(child)

import sap

scene = sap.graphics.factory.ActiveSceneReader

for node in scene.RootNodes:
    iteratenodes(node)


ActiveSceneManager

The Collapse method is included only from VEG 8.0 SP4 or later.

This object is used to modify elements in the scene. Modifications do not persist automatically. The go_scene_save operation has to be called to persist changes to a disk file.

All scene changes are transactional in nature, and must be performed by calling the BeginChanges() method of this interface, followed by the changes to perform, followed by a Commit() call on the object returned by BeginChanges().

Attempting to perform a scene change outside of a BeginChanges()…Commit() scope will cause an exception to be raised.

The scene manager implements the ISceneReader interface as well as the ISceneReaderWriter interface, however, properties that return modifiable scene elements return *ReaderWriter objects that correspond to their Reader equivalents, for example, INodeReaderWriter has all of the properties of INodeReader, but also adds read-write access to select properties.

Properties
PropertyDescription
BomsA sequence of IBomReaderWriter for all BOMs in the scene
CurrentBomAn IBomReaderWriter representing the currently active BOM
HasAssemblyHierarchy Indicates whether the current scene has assembly (instance-reference) hierarchy.
NumberOfFaces

Gets the number of faces the current scene has.

NumberOfVertices

Gets the number of vertices the current scene has.

ProceduresA sequence of IProcedureReader for all procedures in the scene. A procedure has multiple steps.
PortfoliosA sequence of IPortfolioReader for all portfolios in the scene.
RootNodes

A sequence of INodeReaderWriter representing the public root nodes of the current BOM. Equivalent to: scene.CurrentBom.RootNodes.

RootNodesIncludingInternalA sequence of INodeReaderWriter representing all root nodes of the current BOM. Equivalent to: scene.CurrentBom.RootNodesIncludingInternal.
SourceFilePathA string containing the path to the source file this scene was opened from.
Methods
MethodDescription
ActivateBom(bom)

Activates a BOM. The scene's CurrentBom property will be set to this BOM once the modification scope is committed.

ArgumentDescription
bomAn IBomReader or IBomReaderWriter representing the BOM to activate
ActivateModelview(modelview)

Activates a model view.

ArgumentDescription
modelviewAn IModelviewReader representing the model view to activate.
ActivateStepview(step)

Activate the given step of a procedure.

ArgumentDescription
stepAn IStepReader representing the step view to activate.
BeginChanges()

Starts a new change scope. Nested change scopes are not permitted. All scene changes made after this call will be added to this scope, to be applied when the scope is committed.

Return Value
An ISceneChangeScope object that can be used to commit the changes.
 Collapse()

 Accepts an arbitrary collection of nodes, collapses them and adds the collpased node as a child of the youngest common ancestor of the input set nodes.

ArgumentTypeMandatoryDescription
targetNodesIEnumerable<INodeReader>YesNodes to be collapsed
CreateNode(name)

Creates a top-level node in the scene with the specified.

Return Value
An INodeReaderWriter object.
DeleteAllPortfolios()Deletes all portfolios and their ModelViews from the scene. This operation will modify the scene permanently and is not undoable.
DeleteViewport(viewport)Deletes supplied viewport. Portfolios and ModelViews are Viewports. This method accepts both. If a porftolio is being deleted, all its child ModelViews will be automatically deleted too. This operation will modify the scene permanently and is not undoable.
ExecuteQuery()

Executes an RHQ query on this scene.

ArgumentType and Description
queryString - the query text
Return Value 
True if query succeeded, false otherwise.
ExecuteQueryFromFile()

Executes an RHQ query on this scene.

ArgumentType and Description
queryFilePathString - Fully qualified path to the RHQ file containing the query to execute.
Return Value
True if query succeeded, false otherwise.
ReGenerateHiddenCADMetadata()Creates hidden metadata values as they were in VEG 8.0 for RH format. This function was added for backward compatibility for clients who still use RH format and their processing depends on that hidden metadata. After the metadata is created, the file has to be saved to RH format because VDS format will not support it.
RemoveAssemblyHierarchy()

Removes assembly (instance-reference) hierarchy from the scene. This operation will modify the scene permanently and is not undoable. It is a prerequisute for scene hierarchy modification operations.

RenameViewport(viewport)Changes the name of supplied viewport. Portfolios and ModelViews are Viewports. This method accepts both. This operation will modify the scene permanently and is not undoable.
Example 1
scene = sap.graphics.factory.ActiveSceneManager
nodesToBeCollapsed = []
 
for node in scene.RootNodes:
    if node.Name == '_moto_x_asm' or node.Name == 'Skateboard':
        nodesToBeCollapsed.append(node)
        for rootChild in node.Children:
            if rootChild.Name == 'BODY_PANELS_ASM':
                nodesToBeCollapsed.append(rootChild)
 
with scene.BeginChanges():
  scene.ActivateBom(list(scene.Boms)[1])
  scene.Collapse(nodesToBeCollapsed)
Example 2 

This example renames a portfolio named "Portfolio 1" to "My fancy portfolio".

scene = sap.graphics.factory.ActiveSceneManager
  
with scene.BeginChanges():
  for portfolio in scene.Portfolios:
    if portfolio.Name == 'Portfolio 1':
      scene.RenameViewport(portfolio, 'My fancy portfolio')
Example 3 

This example deletes portfolio's "Portfolio 1" ModelViews

scene = sap.graphics.factory.ActiveSceneManager
  
with scene.BeginChanges():
  for portfolio in scene.Portfolios:
    if portfolio.Name == 'Portfolio 1':
      for modelview in portfolio.Modelviews:
        scene.DeleteViewport(modelview)
Example 4 

This deletes all portfolios

scene = sap.graphics.factory.ActiveSceneManager
  
with scene.BeginChanges():
  scene.DeleteAllPortfolios()
Example 5 

This creates hidden metadata for backward compatibility with custom processes

scene = sap.graphics.factory.ActiveSceneManager

with scene.BeginChanges():
     scene.ReGenerateHiddenCADMetadata()


ISceneChangeScope

This is the interface for the object returned by ISceneManager.BeginChanges(). Only one of these can exist at a time within a Visual Enterprise Generator process, nesting is not permitted, and will cause an exception to be raised.

Methods
MethodDescription
Commit()Commits all changes in the current scope and modifies the correspend elements in the scene. No elements in the scene will be modified until this method is called.
Discard()Discards all changes in the current scope. No objects will be modified.

Because changes are only made to scene objects when the scope is committed, if you read a modified property before its change is committed, you will still see the old value.


IBomReaderWriter

This is a superset of IBomReader, which exposes INodeReaderWriter versions of its child nodes. Everything else about the interface is the same.


INodeReaderWriter

The methods Collapse, ChangeMetadata, RemoveMetadata are included only in VEG 8.0 SP 04 or later.

This is a superset of INodeReader, and includes all of the properties of INodeReader, but it also makes some properties writable, and adds some methods.

Writable Properties
PropertyDescription
ClosedWhether or not the node is closed, can be set to true or false
NameThe name of the object, can be set to a new name.
SelectedGets or sets the node selection status. Setting the node selection status will only take effect when the containing change scope is committed.
Additional Methods
MethodDescription
AssignMaterial()

Assigns specified material to the selected node. The material MUST exist on the scene before calling this method. If the material wasn't previously present, it can be added to the scene by using operation “go_material_import” with parameter “filename” value as path to material file e.g. “Gem Emerald.rhm”

ArgumentTypeMandatoryDescription
materialstringYesThe name of the material that has to be assigned to the node
Delete()Deletes this node. If this node is part of an instanced parent object, it will be deleted from all instances.
Collapse()
Collapses the scene hierarchy below this node.
ChangeMetadata() 

Allows setting of new metadata and changing of existing metadata on this node. Metadata can also be changed on all instances of this node.

ArgumentTypeMandatoryDescription
categorystringYesThe category of the new metadata to be set or existing metadata to be changed.

keyname

stringYesThe key of the new metadata to be set or existing metadata to be changed.
valueobjectYesThe metadata value to be set
setOnAllInstances bool No Indicates whether the metadata change should be reflected on all instances of the node. Treated as set to false, if not explicitly set to true.
MovePivotPointObjCenter()
Moves the pivot point of the object represented by this node to the object's center.
MovePivotPointSceneCenter()
Moves the pivot point of the object represented by this node to the whole scene's center.
RemoveMetadata()

Allows removal of metadata under the specified category and keyname on this node. If no keyname is specified, all metadata under the category is removed. Metadata can also be removed from all instances of the node.

ArgumentTypeMandatoryDescription
category                          stringYes             The category of the metadata to be removed.

keyname

stringNoThe keyname category of the metadata to be removed.
removeOnAllInstancesboolNoIndicates if the metadata removal is to affected on all instances of the node. Treated as set to false, if not explicitly set to true.
SetParent()

Changes the node parent. This will only take effect when the containing change scope is committed, if the parent node is not null and if the scene does not contain any assembly (instance-reference) hierarchy.

ArgumentTypeMandatoryDescription
parentINodeReaderYesThe new parent node
Example
scene = sap.graphics.factory.ActiveSceneManager
metadataToBeSet = ["KNA1","VBKA", "VBAK", True, 7642, 16.25]
with scene.BeginChanges():
  for node in scene.RootNodes:
    if node.Name == 'DeleteMe':
		node.Delete()
    else:
        node.Name = 'PREFIX' + node.Name
    if node.Name == 'System Wheel':
        node.ChangeMetadata('SAP', 'MATERIAL', '100000045786', True)
        node.ChangeMetadata('SAP', 'SALES', metadataToBeSet)
        node.RemoveMetadata('SAP', 'QUANTITY')
        node.RemoveMetadata('CADMetadata')
        wheelChild.RemoveMetadata('VE', removeOnAllInstances=True)
        node.MovePivotPointObjCenter()
        node.AssignMaterial("Gem Emerald")
        	


sap.workflow.settings

This object provides access to the workflow settings for the current job. 

Methods
MethodDescription
GetValueByName(name)

Gets the workflow setting by setting name. Uses case sensitive comparison.

ArgumentDescription
name

A string containing the name of the setting. The name of a setting is different from the display name, and is unaffected by system locale settings.

The setting name can be found in Visual Enterprise Generator 8.0 SP2 or later, when editing the settings for a particular workflow in the Visual Enterprise Generator Administration tool, above the description of the setting in italics:

GetValueByDisplayName(displayName)

Gets a workflow setting by setting display name. Uses case insensitive comparison.

ArgumentDescription
displayNameThe display name of the setting.

The setting display name is not locale independent, therefore, if the system locale changes (for example, from English to German), this lookup may fail because the display name used will change based on the system locale. If this is a problem, use the setting name instead.


Example

This example retrieves a workflow setting by name and display name.

workflowSettings = sap.workflow.settings
 
# Retrieve setting by name
setting = workflowSettings.GetValueByName("StorageCategory")
sap.log.info("Setting 'StorageCategory' value is '%s'" % setting)
 
# Retrieve setting by display name (a collection of matches is returned)
settingCollection = workflowSettings.GetValueByDisplayName("storage category")
sap.log.info("Found %s values for setting 'storage category'" % settingCollection.Count())
for setting in settingCollection:
  sap.log.info(" - Setting 'storage category' value is '%s'" % setting)


# Retrieve setting by name using indexer
setting = workflowSettings["StorageCategory"]
sap.log.info("Setting 'StorageCategory' value is '%s'" % setting)

 

sap.job.startup_arguments

This object provides access to the start-up arguments for the current job.

This object is only included in Visual Enterprise Generator 8.0 SP4 or later.


Methods
MethodDescription
GetValueByName(name)

Gets the start-up argument by start-up argument name. Uses case sensitive comparison.

ArgumentDescription
name

A string containing the name of the start-up argument.

The start-up argument name can be found in Visual Enterprise Generator 8.0 or later, when viewing the job report for a particular job in the Visual Enterprise Generator Administration tool:

 

Example

This example retrieves a job start-up argument by name.

jobStartupArgs = sap.job.startup_arguments
 
# Retrieve start-up argument by name
startupArg = jobStartupArgs.GetValueByName("ExtractAllConfigsIfNoneSpecified")
sap.log.info("Start-up argument 'ExtractAllConfigsIfNoneSpecified' value is '%s'" % startupArg)
 
# Retrieve start-up argument by name using indexer
startupArg = jobStartupArgs["ExtractAllConfigsIfNoneSpecified"]
sap.log.info("Start-up argument 'ExtractAllConfigsIfNoneSpecified' value is '%s'" % startupArg)


sap.process.settings

This object provides access to process settings.

Properties
PropertyDescription
StartTimeGets the timestamp for the time that the process started executing, as a .NET DateTime structure
TimeOutGets the timeout of the process in seconds, as an integer value
TimeOutTimeGets the the time when this process will timeout, as a .NET DateTime structure
Example

Logs the process settings.

processSettings = sap.process.settings
sap.log.info("Process started at '%s' with a timeout of %s seconds and will be killed at '%s' if it does not complete by then." % (processSettings.StartTime, processSettings.TimeOut, processSettings.TimeOutTime))

 

sap.jobid

Returns the job ID of the current job, as a 64-bit integer.

sap.parentjobid

Returns the job ID of the parent job, if any, otherwise, returns 0, as a 64-bit integer.


Web Service API

The VDI web service API is a new web service in Visual Enterprise Generator 8.0 for triggering and managing VDI workflow jobs. It is used by the Upload Client to start and manage conversion jobs, and can also be used by third parties for a more advanced integration with Visual Enterprise Generator.

Getting Started

Please refer to note 1694219 , attachment WebService VDI VEG 9.0.zipfor the WSDL for this web service. The WSDL file is named ERPIntegrationService.wsdl, use this file to generate your proxies for communicating with this service.

Consumers of this web service must support streaming MTOM in order to upload files to be used by jobs, this is supported by .NET and modern Java web service stacks.

Workflow List

To get the list of possible VDI workflows that jobs can be started for, the method WorkflowGetAvailable() can be called without having performed any authentication.

WorkflowGetAvailableResponse

This is the response object returned by WorkflowGetAvailable().

Field NameTypeMandatoryDescription
WorkflowSystemConnectionsArray of WorkflowSystemConnectionYesThe list of VDI workflows that can be used for conversion jobs
WorkflowSystemConnection
Field NameTypeMandatoryDescription
WorkflowNameStringYesThe name of the VDI workflow.
ClientNameStringNoThe client of the SAP system associated with the workflow (e.g. 002)
SystemNameStringNo

The name of the SAP system associated with the workflow.

Corresponds to the name in SAP GUI on the server and user account where Visual Enterprise Generator has been configured. This name should match up with the name used in SAP GUI on the system where the Upload Client is used, for document linking in Upload Client to work.

 

Authentication

In order to use any of the authenticated web service calls, a call to the UserAuthenticate() web service method must be performed to obtain a session ID which should be supplied with all subsequent requests, and acts as an authentication token.

If authentication fails, a SOAP fault will be raised by this call with more information.

UserAuthenticateRequest

This is the request object which must be passed into UserAuthenticate().

Field NameTypeMandatoryDescription
UserNameStringYesThe SAP user name to authenticate. This should be the name of a user in the SAP system associated with the workflow.
PasswordStringYesThe password of the user being authenticated
WorkflowNameStringYesThe name of the workflow against which to authenticate the user. The workflow will have an associated SAP system.
CultureNameStringYesThe culture name to use for the user. This affects functions which support localized values, like the localized job report retrieval. This value is in the Windows culture name format, see the Culture Name column in http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx for a list of possible values.
ShouldCreateSessionBooleanNoWhether or not an isual Enterprise Generator user session should be created. This should be set to true if subsequent calls will be made which use the created session, and  set to false if the authentication request will not be followed by subsequent calls, and it is just an authentication check.
UserAuthenticateResponse

This is the response object returned by UserAuthenticate() in the event of successful authentication.

Field NameTypeMandatoryDescription
SessionIdStringYesThe session ID that can be used as an authentication token in subsequent web service calls, by passing it through in the SessionId field of other request objects.

 

Deauthentication

In order to preemptively clear user sessions, the method UserDeauthenticate() can be called to delete a session and all information associated with it.

UserDeauthenticateRequest

This is the request object which must be passed in to UserDeauthenticate().

Field NameTypeMandatoryDescription
SessionIdStringYesThe session ID obtained from a previous UserAuthenticate() call.

 

UserDeauthenticateResponse

This object contains no fields.

 

File Uploading

All conversion jobs started using this web service require an input file in order to start. This file should be uploaded to the server first before starting the job.

The sequence of events is as follows:

  1. The FileUploadBegin() method is called to obtain a unique ID for the file to be uploaded.
  2. The FileUploadChunk() method is called as many times as needed to transfer all the file data to the server.
  3. The FileUploadEnd() method is called to mark an uploaded file as complete. After making this call the file unique ID can be passed to methods that expect it.

FileUploadBegin()

This method generates a new unique ID to use for subsequent file upload calls.

FileUploadBeginRequest

This is the request object that must be passed into the FileUploadBegin() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
FileUploadBeginResponse

This is the response object returned by the FileUploadBegin() call.

Field NameTypeMandatoryDescription
UniqueIdStringYesThe unique ID for the file

 

FileUploadChunk()

This method uploads a chunk of a file to the server. If an error occurs, a SOAP fault will be raised by this call, containing additional information.

FileUploadChunkRequest

This is the request object that must be passed into the FileUploadChunk() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
UniqueIdStringYesThe unique ID for the file a chunk is being uploaded for
OffsetIntegerYesThe starting offset in the file where the data for this chunk should be written
LengthIntegerYesThe size in bytes of this chunk
StreamByte ArrayYesThe data for this chunk. Depending on the platform, this will be represented as a Stream on .NET, or a byte array on Java (depending on the web service stack). Transported using MTOM encoding.
FileUploadChunkResponse

This object contains no fields.

 

FileUploadEnd()

This methods marks a file which was being uploaded as completed. The file cannot be written to after this call.

FileUploadEndRequest

This is the request object that must be passed into the FileUploadEnd() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
UniqueIdStringYesThe unique ID of the file to mark as completed, obtained from a previous FileUploadBegin() call

FileUploadCancel()

This methods removes all information for a file which was being uploaded. The file cannot be written to after this call, and the unique ID no longer exists on the server.

FileUploadCancelRequest

This is the request object that must be passed into the FileUploadCancel() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
UniqueIdStringYesThe unique ID of the file to remove, obtained from a previous FileUploadBegin() call

 

Starting Jobs

Once the input file to a job has been uploaded, the job can be started by invoking JobStartWithUploadedFile(). If the job could not be started successfully, a SOAP fault is raised.

JobStartWithUploadedFileRequest

This is the request object that must be passed into the JobStartWithUploadedFile() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
InputFileUniqueIdStringYesThe unique ID of the uploaded file which should be used as the input to the VDI processing job
WorkflowNameStringYesThe name of the VDI workflow for which to start a job
JobNameStringNoThe name to give the processing job
JobStartWithUploadedFileResponse

This is the response object returned by the JobStartWithUploadedFile() call.

Field NameTypeMandatoryDescription
JobIdIntegerYesThe Visual Enterprise Generator job ID for the started job

 

Canceling Jobs

 To cancel a currently running job, the JobCancel() method can be invoked. If the job could not be canceled successfully, a SOAP fault is raised.

JobCancelRequest
Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
VegJobIDIntegerYesThe Visual Enterprise Generator job ID of the job to cancel

 

JobCancelResponse

 This object contains no fields.


Job Monitoring

To query the status of running jobs, in order to determine whether or not they have completed, the JobGetStatus() call can be used.

JobGetStatusRequest

This is the request object that must be passed into the JobGetStatus() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
JobIDsArray of IntegerYesAn array of the Visual Enterprise Generator job IDs to query
JobGetStatusResponse

This is the response object returned by the JobGetStatus() call.

Field NameTypeMandatoryDescription
JobsArray of JobStatusInfoYesAn array of JobStatusInfo objects, corresponding to each job ID supplied in the request JobIDs field.
JobStatusInfo

This is the type of an element in the Jobs field of the JobGetStatusResponse object.

Field NameTypeMandatoryDescription
IdIntegerYesThe Visual Enterprise Generator job ID with which this status object is associated
StatusEnumYes

The current status of this job. Possible values are the following:

  • Unknown: Job does not exist or status could not be determined
  • Queued: Job has been queued with Visual Enterprise Generator
  • Running: Job is currently running
  • Completed: Job has finished, consult the Outcome field to determine whether or not it was successful
OutcomeEnumNo

This field is only set to a meaningful value if the job Status is Complete. Possible values are the following:

  • Unknown: Job does not exist or is not yet complete
  • Success: Job completed with no errors or warnings
  • Warning: Job completed, but there were some warnings
  • Error: Job completed, but there were some errors
  • Aborted: Job was canceled by user
  • Paused: Job is currently paused


Job Results

After a job completed successfully, it can be useful to programmatically retrieve information about what actions the job performed. As an example, it is possible to programmatically determine the SAP DIR IDs for completed jobs, as well as whether or not those jobs have viewables attached to the DIRs.

This is achieved by calling the JobGetResult() method.

JobGetResultRequest

This is the request object that must be passed into the JobGetResult() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
JobIDsArray of IntegerYesAn array of the Visual Enterprise Generator job IDs to query
JobGetResultResponse

This is the response object returned by the JobGetResult() call.

Field NameTypeMandatoryDescription
JobsArray of JobResultInfoYesAn array of JobResultInfo objects, corresponding to each job ID supplied in the request JobIDs field.
JobResultInfo

This is the type of an element in the Jobs field of the JobGetResultResponse object.

Field NameTypeMandatoryDescription
IdIntegerYesThe Visual Enterprise Generator job ID with which this result object is associated
ResultsArray of JobResultYes

An array of JobResult objects containing the results for the job

JobResult

This is the type of an element in the Results field of the JobResultInfo object.

Field NameTypeMandatoryDescription
CategoryStringNoThe category of this result (a grouping field). VDI workflows will use a category of SAP for system created results.
PathStringNo

The path of the result (a sub-grouping field). The value used here is workflow-specific.

NameStringYesThe name associated with the result
ValueStringYesThe value associated with the result

 

Job Reporting

The job report is a human-readable report of what occurred in a job, it is not intended for machine consumption, since different languages will result in completely different data in the returned XML.

A job report is retrieved by invoking the JobGetLocalisedReportAsXml() method.

JobGetLocalizedReportRequest

This is the request object passed to JobGetLocalisedReportAsXml().

Field NameTypeMandatoryDescription
JobIdIntegerYesThe Visual Enterprise Generator job ID for which to get the job report
LanguageStringNo

The ISO 3166 two letter language code specifying the language in which the job report should be returned.

Not all languages have localisations for the job report. The major supported languages are English, German, Chinese, Japanese, Russian, Spanish, and Portuguese.

JobGetLocalizedReportResponse

This is the response object returned by JobGetLocalisedReportAsXml().

Field NameTypeMandatoryDescription
JobReportStringYesThe localised job report, in XML format.

 

Appendix A: Creating a Scriptable Operation

Scriptable operations are created inside the Process Designer, with either a new or existing process opened.

To create the definition for a new scriptable operation, choose Operations -> New Scriptable Operation.

To edit the definition of an existing scriptable operation, open the toolbox where the operation was saved, right-click the operation, and choose Edit.

This will display the Operation Editor window for the new operation:

The Operation Editor lets you modify the operation name and display name (for new operations), the description, and the input and output parameters that will be available to pass data in and out of the operation.

Right-click a parameter in the Input or Output panel to edit advanced properties of the parameter or change its default assigned name.

If you set the value of the code sub-parameter of the script parameter to some Python script code, this will be the default code for new instances of this operation. You can use this feature to implement operations solely using Python. Note: This requires Visual Enterprise Generator 8.0 SP2 or later.

 

 

 

  • No labels