Class WebRequestTask

Namespace

ArcanaDevelopment.adTempus.Client

Assembly

ArcanaDevelopment.adTempus.Client.dll

Task that sends a request to w Web server

public sealed class WebRequestTask : Task

Inheritance

object

ObjectBase

ADTObject

Task

WebRequestTask

Properties

AcceptAnyStatusCode

Specifies whether the task succeeds regardless of the HTTP status code returned.

public bool AcceptAnyStatusCode { get; set; }

Property Value

bool

Remarks

Default: false, in which case a status code outside the range 200-299 causes the task to fail. The status code is always available in the WebRequest.StatusCode variable.

AuthenticationType

The authentication method used for the request.

public WebRequestAuthenticationType AuthenticationType { get; set; }

Property Value

WebRequestAuthenticationType

Remarks

Default: JobIdentity

AutoMapFilter

The paths to convert when AutoMapResponse is true.

[CanBeNull]
public string AutoMapFilter { get; set; }

Property Value

string

Remarks

A list of paths separated by commas or semicolons. Prefix a path with "-" to exclude it, and use "*" as a wildcard. A path also selects everything beneath it. If no paths are included, all paths that are not excluded are converted.

AutoMapResponse

Specifies whether a JSON or XML response is converted to job variables automatically.

public bool AutoMapResponse { get; set; }

Property Value

bool

Remarks

Default: false. Each value in the response becomes a variable named with the AutoMapVariablePrefix followed by its path (for example, "WebRequest.Response.data.items[0].id").

See Also

AutoMapFilter

AutoMapVariablePrefix

The prefix for variables created when AutoMapResponse is true.

[CanBeNull]
public string AutoMapVariablePrefix { get; set; }

Property Value

string

Remarks

Default: "WebRequest.Response."

BodyType

Specifies how the request body is constructed.

public WebRequestBodyType BodyType { get; set; }

Property Value

WebRequestBodyType

Remarks

Default: None. For Raw, the body is taken from RequestBody. For the other types the body is built from the Parameters whose Location is Body.

CaptureResponseHeaders

Specifies whether response headers are stored in job variables named "WebRequest.ResponseHeader.name".

public bool CaptureResponseHeaders { get; set; }

Property Value

bool

Remarks

Default: false

See Also

ResponseHeaderFilter

ClassID

The Class ID for the object

[IgnoreDataMember]
public override ClassID ClassID { get; }

Property Value

ClassID

ClassKeyName

The key name for the class.

public override string ClassKeyName { get; }

Property Value

string

Remarks

This name the name used by adTempus to identify the class and is intended for programmatic use only. Use the ClassName for a user-friendly name.

ContentType

The content type of the body when BodyType is Raw (for example, "application/json").

[CanBeNull]
public string ContentType { get; set; }

Property Value

string

Remarks

Variable tokens can be used in the value.

CredentialProfile

The credential profile that supplies the credentials for the request.

[CanBeNull]
public CredentialProfile CredentialProfile { get; set; }

Property Value

CredentialProfile

Remarks

Required for CredentialProfile authentication, where the credentials are used for Windows authentication. Optional for Basic authentication: if a profile is specified, its user ID and password are sent instead of UserID and the password set with SetPassword(string). Ignored for other authentication types.

FollowRedirects

Specifies whether redirect responses are followed automatically.

public bool FollowRedirects { get; set; }

Property Value

bool

Remarks

Default: true

Headers

The request headers.

[NotNull]
public WebRequestHeaderList Headers { get; }

Property Value

WebRequestHeaderList

Remarks

Variable tokens can be used in header values. Use SetSecretValue(string) for values such as API keys that should be stored encrypted.

IgnoreCertificateErrors

Specifies whether server certificate errors are ignored.

public bool IgnoreCertificateErrors { get; set; }

Property Value

bool

Remarks

Default: false. Use only for testing or for trusted servers with self-signed certificates.

IsDependent

Indicates whether the object is a dependent of (owned by) another object

[IgnoreDataMember]
public override bool IsDependent { get; }

Property Value

bool

Remarks

An independent object (IsDependent is false) is an object that can exist on its own without being part of another object. For example, Jobs, Job Groups, etc.

A dependent object (IsDependent is true) is a part of another object. For example, a JobStep cannot exist independently of a Job, so the JobStep is dependent.

Dependent objects cannot be directly fetched from the server: they are only fetched as part of the object they belong to. They also cannot be saved or deleted independently: they are automatically saved or deleted when the owning object is saved or deleted.

MaxRunTime

The maximum execution time for the download. If the download exceeds the specified time it will be terminated.

public TimeSpan? MaxRunTime { get; set; }

Property Value

TimeSpan?

Remarks

Set to null or System.TimeSpan.Zero for no limit.

MaxVariableSize

The maximum number of characters stored in any job variable set by the task.

public int MaxVariableSize { get; set; }

Property Value

int

Remarks

Default: 1048576. Longer values are truncated and a warning is logged. Specify 0 for no limit.

OAuthClientAuthentication

Specifies how the client ID and client secret are sent when requesting an access token for OAuth2ClientCredentials authentication.

public WebRequestOAuthClientAuthentication OAuthClientAuthentication { get; set; }

Property Value

WebRequestOAuthClientAuthentication

Remarks

Default: RequestBody. Some token endpoints accept only BasicAuthorizationHeader.

OAuthScope

The scope requested for OAuth2ClientCredentials authentication.

[CanBeNull]
public string OAuthScope { get; set; }

Property Value

string

Remarks

Optional. Variable tokens can be used in the value.

OAuthTokenParameters

Additional parameters sent with the access token request for OAuth2ClientCredentials authentication.

[NotNull]
public OAuthTokenParameterList OAuthTokenParameters { get; }

Property Value

OAuthTokenParameterList

Remarks

Use for parameters required by some token endpoints, such as audience or resource. Values can contain variable tokens, and SetSecretValue(string) can be used for values that should be stored encrypted. Parameters named grant_type, client_id, client_secret, or scope are ignored, because they are set from the other OAuth settings.

OAuthTokenURL

The URL of the token endpoint for OAuth2ClientCredentials authentication.

[CanBeNull]
public string OAuthTokenURL { get; set; }

Property Value

string

Remarks

Variable tokens can be used in the value.

Parameters

The query string and body parameters.

[NotNull]
public WebRequestParameterList Parameters { get; }

Property Value

WebRequestParameterList

Remarks

Variable tokens can be used in parameter values. Use SetSecretValue(string) for values that should be stored encrypted.

PasswordSet

Indicates whether a password, token, or client secret has been set.

public bool PasswordSet { get; }

Property Value

bool

RequestBody

The body of the request when BodyType is Raw.

[CanBeNull]
public string RequestBody { get; set; }

Property Value

string

Remarks

Variable tokens can be used in the value.

RequestMethod

The HTTP method to use when sending the request.

[CanBeNull]
public string RequestMethod { get; set; }

Property Value

string

Remarks

Any method can be specified (for example, GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS). If no method is specified, a GET is performed.

RequestURL

The URL to request.

[CanBeNull]
public string RequestURL { get; set; }

Property Value

string

Remarks

This value is required. Variable tokens can be used. The protocol (e.g., "http://") must be included.

ResponseExtractions

Rules that extract values from the response into job variables.

[NotNull]
public WebResponseExtractionList ResponseExtractions { get; }

Property Value

WebResponseExtractionList

ResponseHeaderFilter

The headers to store when CaptureResponseHeaders is true.

[CanBeNull]
public string ResponseHeaderFilter { get; set; }

Property Value

string

Remarks

A list of header names separated by commas or semicolons. Prefix a name with "-" to exclude it, and use "*" as a wildcard. If no names are included, all headers that are not excluded are stored. If the value is empty, all headers are stored.

ResponseScript

The script that is run to process the response.

[CanBeNull]
public Script ResponseScript { get; set; }

Property Value

Script

Remarks

Optional. The script must be based on WebResponseScriptBase. The script is run only if the request succeeds.

ResponseVariable

The job variable that receives the response body.

[CanBeNull]
public string ResponseVariable { get; set; }

Property Value

string

Remarks

Optional. The value is limited to MaxVariableSize characters.

RetryCount

The number of times the request is retried after a connection failure or a status code listed in RetryStatusCodes.

public int RetryCount { get; set; }

Property Value

int

Remarks

Default: 0

RetryDelay

The number of seconds to wait between retries.

public int RetryDelay { get; set; }

Property Value

int

Remarks

Default: 30. A longer delay requested by the server in a Retry-After header is honored.

RetryStatusCodes

The HTTP status codes that cause the request to be retried.

[CanBeNull]
public string RetryStatusCodes { get; set; }

Property Value

string

Remarks

A list of codes or ranges separated by commas (for example, "429,500-599"). Default: "408,429,500,502,503,504".

SaveAsCapturedFile

Specifies whether the save the requested page or file as a Captured File in the job history.

public bool SaveAsCapturedFile { get; set; }

Property Value

bool

Remarks

Default: false

See Also

SaveToLocation

SaveToLocation

Specifies the file name to use to save the requested page or file.

[CanBeNull]
public string SaveToLocation { get; set; }

Property Value

string

Remarks

If a file name is specified, the requested page or file is saved to it. If no SaveLocation is specified, the file is not saved.

Variable tokens can be used in the value.

See Also

SaveAsCapturedFile

SupportedResponseEvents

Gets a list of the events that are supported for Responses associated with this task.

public override ReadOnlyCollection<SupportedResponseEvent> SupportedResponseEvents { get; }

Property Value

ReadOnlyCollection<SupportedResponseEvent>

UserID

The user ID for Basic authentication, or the client ID for OAuth2ClientCredentials.

[CanBeNull]
public string UserID { get; set; }

Property Value

string

Remarks

Variable tokens can be used in the value.

UsesCredentialProfile

Indicates whether the credentials for the request come from CredentialProfile.

public bool UsesCredentialProfile { get; }

Property Value

bool

Methods

ApplyCurlRequest(CurlRequest)

Applies settings parsed from a curl command line to the task.

public void ApplyCurlRequest(CurlRequest request)

Parameters

Name	Type	Description
request	CurlRequest	The parsed request.

Remarks

Replaces the method, URL, headers, parameters, and body. Authentication and options are changed only if the command specified them.

GetObjectDescription()

Gets a description of the object's key settings.

protected override string GetObjectDescription()

Returns

string

Remarks

This method is called by GetDescription to get a user-friendly description of the object (such as its key settings) for display to the user. The description should contain enough information to distinguish this object from others of the same class.

GetReferencedVariableNames(IEnumerable<string>)

Gets the names of the job variables used by the task's request settings.

[NotNull]
public IReadOnlyList<string> GetReferencedVariableNames(IEnumerable<string> definedVariableNames = null)

Parameters

Name	Type	Description
definedVariableNames	IEnumerable<string>	The names of the variables defined for the job, if available. Used to recognize names that are valid only under the variable naming rules of earlier versions.

Returns

IReadOnlyList<string>

The distinct variable names, in the order in which they are first used.

Remarks

The URL, method, body, content type, enabled headers and parameters, authentication settings, and OAuth token request settings are searched. The response settings are not.

Secret values and the password that have been saved cannot be retrieved, so variables used in them are not included. Secret values that have been entered but not yet saved are searched.

SetPassword(string)

Sets the password for Basic authentication, the token for Bearer, or the client secret for OAuth2ClientCredentials.

public void SetPassword(string value)

Parameters

Name	Type	Description
value	string	The new value. Variable tokens can be used.

Remarks

The value is stored encrypted and cannot be retrieved, only set.

See Also

PasswordSet

TestRequest(Dictionary<string, string>, CredentialProfile)

Sends the request on the server as a test and returns the response.

public WebRequestTestResult TestRequest(Dictionary<string, string> variableValues, CredentialProfile credentialProfile = null)

Parameters

Name	Type	Description
variableValues	Dictionary<string, string>	Values for variable tokens used by the task, overriding server and job values. Can be null.
credentialProfile	CredentialProfile	The account to use for JobIdentity authentication. If null, the job's account is used.

Returns

WebRequestTestResult

The response, the variables the task would set, and any errors.

Remarks

The task's current settings are used, including unsaved changes. No files are saved and no response script is run. Secret values are masked in the result.

ToCurlRequest()

Converts the task's request settings to a CurlRequest.

[NotNull]
public CurlRequest ToCurlRequest()

Returns

CurlRequest

Remarks

Used to produce a curl command line. Secrets that have been saved cannot be retrieved and are left empty.

WriteToConfigurationReport(IADTObjectConfigurationReportWriter)

Writes the object and any contained objects to a configuration report

public override void WriteToConfigurationReport(IADTObjectConfigurationReportWriter reportBuilder)

Parameters

Name	Type	Description
reportBuilder	IADTObjectConfigurationReportWriter	The report builder to write the object to.

Inherited Members

• UserInterfaceExtensionID
• UserInterfaceExtensionData
• DescriptionOverride
• JobStep
• LastModified
• CreationTimestamp
• FromController
• CustomProperties
• Description
• DescriptionTextType
• OID
• BindingDescription
• ToString()
• ParentObject
• CanPerform(SecurityPermission)
• Duplicate()
• DataContext
• AccessMask
• Validate(MessageCollection)
• SupportedSecurityActions
• SupportedSecurityInheritanceOptions
• GetTopLevelOwner()
• GetConfigurationReport()
• GetConfigurationReport(bool)
• IsReadOnly
• IsDirty
• IsNew
• IsStub
• ClassName
• GetDescriptionWithClassName()
• GetDescription()
• BeginEdit()
• BeginEdit(UndoLevelAction)
• CommitEdit(Guid)
• CommitEdit()
• UndoEdit()
• UndoEdit(Guid)