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.

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.

Methods

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

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

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. Prior to version 9.10 (9.0 FP10) the default timeout was 100 seconds and not customisable. From version 9.10 (9.0 FP10) the default timeout is 30 minutes and can be changed.

Properties

Methods

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', 500)
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')

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

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

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

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.

first_bom = scene.Boms[0]        # NOT correct 
first_bom = list(scene.Boms)[0]  # correct
last_bom = list(scene.Boms)[-1]  # correct

Properties

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

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

Properties

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.

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

Example

metadata = scene.CurrentBom.Metadata.MetadataValues

IBomReader

This interface defines read access to a BOM object.

Properties

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

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

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.

Properties

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

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

IIdentifierField

Represents VE identifier field

Properties

IObjectReader

This interface defines read access to a graphics object.

Properties

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

Example

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

IModelViewReader

This object provides read access to a model view.

Properties

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

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

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

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

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().

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

Methods

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()

Example 6 

This applies metadata from manifest. Available in version 9.10 (9.0 FP10) onward.

import sap

scene = sap.graphics.factory.ActiveSceneManager
with scene.BeginChanges():
   scene.ApplyMetadataFromManifest(sap.input_parameters['Schema1FilePath'])

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

IBomReaderWriter

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

INodeReaderWriter

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

Additional Methods

AssignMaterial()

Collapse()

MovePivotPointObjCenter()

MovePivotPointSceneCenter()

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. 

Properties

Example

This example retrieves the workflow name and produces warning message in the log.

sap.log.warning("----Workflow Name is " + sap.workflow.settings.WorkflowName)

Methods

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.

Methods

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

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.zip, for 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().

WorkflowSystemConnection

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().

UserAuthenticateResponse

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

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().

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.

FileUploadBeginResponse

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

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.

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.

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.

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.

JobStartWithUploadedFileResponse

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

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

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.

JobGetStatusResponse

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

JobStatusInfo

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

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.

JobGetResultResponse

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

JobResultInfo

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

JobGetLocalizedReportRequest

This is the request object passed to JobGetLocalisedReportAsXml().