Granta MI connection

Connection builder

class Connection(servicelayer_url, session_configuration=None)

Connects to a Granta MI Server API instance.

This is a subclass of the ansys.openapi.common.ApiClientFactory class. All methods in this class are documented as returning ApiClientFactory class instances of the ansys.grantami.jobqueue.Connection class.

Parameters:

servicelayer_urlstr

Base URL of the Granta MI Service Layer application.

session_configurationSessionConfiguration, default: None

Additional configuration settings for the requests session. If None, the SessionConfiguration class with default parameters is used.

Notes

For advanced usage, including configuring session-specific properties and timeouts, see the OpenAPI-Common API reference documentation. Specifically, see the documentation for the ApiClientFactory base class and the SessionConfiguration class.

1. Create the connection builder object and specify the server to connect to.

2. Specify the authentication method to use for the connection and provide credentials if required.

3. Connect to the server, which returns the client object.

The examples show this process for different authentication methods.

Examples

>>> client = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
>>> client
<JobQueueApiClient: url=http://my_mi_server/mi_servicelayer>

>>> client = (
...     Connection("http://my_mi_server/mi_servicelayer")
...     .with_credentials(username="my_username", password="my_password")
...     .connect()
... )
>>> client
<JobQueueApiClient: url: http://my_mi_server/mi_servicelayer>

with_autologon()

Set up client authentication for use with Kerberos (also known as integrated Windows authentication).

The default operation of this method is to attempt to connect to the API and to use the provided WWW-Authenticate header to determine if Negotiate authentication is supported by the server. If so, Negotiate will then be used for authentication.

If Negotiate authentication is not supported by the server, an exception is raised.

Returns:

ApiClientFactory

Current client factory object.

Raises:

ConnectionError

If the server does not support Negotiate authentication.

Notes

Requires the user to have a valid Kerberos Ticket-Granting-Ticket (TGT).

• On Windows, this is provided by default.

• On Linux, this requires the [linux-kerberos] extension to be installed and your Kerberos installation to be configured correctly.

with_credentials(username, password, domain=None, authentication_scheme=AuthenticationScheme.AUTO)

Set up client authentication for use with provided credentials.

The default operation of this method is to attempt to connect to the API and to use the provided WWW-Authenticate header to determine whether NTLM or Basic Authentication should be used. The selected authentication scheme will then be configured for use.

Parameters:

usernamestr

Username for the connection.

passwordstr

Password for the connection.

domainstr, optional

Domain to use for connection if required. The default is None.

authentication_schemeAuthenticationScheme

The authentication scheme to use.

Tip

Added to ApiClientFactory.with_credentials in version 2.1 of ansys-openapi-common.

Returns:

ApiClientFactory

Original client factory object.

Raises:

ConnectionError

If the server does not support Basic or NTLM authentication (Windows clients only).

Notes

NTLM authentication is not currently supported on Linux.

with_oidc(idp_session_configuration=None)

Set up client authentication for use with OpenID Connect.

Parameters:

idp_session_configurationSessionConfiguration, optional

Additional configuration settings for the requests session when connected to the OpenID identity provider.

Returns:

OIDCSessionBuilder

Builder object to authenticate via OIDC.

Notes

OIDC Authentication requires the [oidc] extra to be installed.

with_anonymous()

Set up client authentication for anonymous use.

This does not configure any authentication or authorization headers. Users must provide any authentication information required themselves.

Clients relying on custom authentication such as client certificates or non-standard tokens should use this method.

Returns:

ApiClientFactory

Original client factory object.

connect()

Finalize the JobQueueApiClient client and return it for use.

Authentication must be configured for this method to succeed.

Returns:

JobQueueApiClient

Client object that can be used to connect to Granta MI and interact with the job queue API.

JobQueue client

class JobQueueApiClient(session, service_layer_url, configuration)

Communicates with Granta MI.

This class is instantiated by the Connection class and should not be instantiated directly.

property processing_configuration: JobQueueProcessingConfiguration

Current job queue configuration information from the server.

Performs an HTTP request against the Granta MI Server API.

Returns:

JobQueueProcessingConfiguration

Current job queue processing configuration on the server.

property is_admin_user: bool

Flag indicating if the current user is an administrator of the job queue.

Administrators can promote jobs to the top of the queue and interact with other users’ jobs.

Performs an HTTP request against the Granta MI Server API.

Returns:

bool

True if the user is an administrator, False otherwise.

property can_write_job: bool

Flag indicating if the current user can create jobs.

Performs an HTTP request against the Granta MI Server API.

Returns:

bool

True if the user can create jobs, False otherwise.

property num_jobs: int

Number of jobs in the job queue, including completed and failed jobs.

Performs an HTTP request against the Granta MI Server API.

Returns:

int

Number of jobs in the job queue.

property jobs: List[AsyncJob]

List of all jobs on the server visible to the current user.

Running or pending jobs are sorted according to their positions in the queue. Completed or failed jobs are returned last.

Performs an HTTP request against the Granta MI Server API.

Returns:

list[AsyncJob]

List of all jobs on the server visible to the current user.

jobs_where(name=None, job_type=None, description=None, submitter_name=None, status=None)

Get a list of jobs on the server matching a query.

Running or queued jobs are sorted according to their positions in the queue. Completed or failed jobs are returned last.

Performs an HTTP request against the Granta MI Server API.

Parameters:

namestr, default: None

Text that must appear in the job name.

job_typeJobType, default: None

Type of job to search for.

descriptionstr, default: None

Text that must appear in the job description.

submitter_namestr, default: None

Text that must equal the name of the user who submitted the job.

statusJobStatus, default: None

Status of the job.

Returns:

list of AsyncJob

List of jobs on the server matching the query.

get_job_by_id(job_id)

Get the job with a given job ID.

Parameters:

job_idstr

Job ID.

Returns:

AsyncJob

Job with the given ID.

delete_jobs(jobs)

Delete one or more jobs from the server.

Parameters:

jobslist of AsyncJob

List of jobs to delete from the server.

create_job_and_wait(job_request)

Create a job from an Excel import or export request or from a text import request.

This method create a job from an ExcelImportJobRequest, ExcelExportJobRequest, or TextImportJobRequest object and waits until the job is complete.

This method also uploads the files included in the job request as a part of the job submission process.

Parameters:

job_requestJobRequest

Job request to submit to the job queue.

Returns:

AsyncJob

Object representing the completed job.

create_job(job_request)

Create a job from an Excel import or export request or from a text import request.

This method creates a job from an ExcelImportJobRequest, ExcelExportJobRequest, or TextImportJobRequest object.

This method also uploads the files included in the job request as a part of the job submission process.

Parameters:

job_requestJobRequest

Job request to submit to the server.

Returns:

AsyncJob

Object representing the in-progress job.