Skip to content

Latest commit

 

History

History
106 lines (85 loc) · 4.59 KB

casefile.md

File metadata and controls

106 lines (85 loc) · 4.59 KB
Raw

Case files

The case file object is a container used to bundle documents and signers. Every signing process starts with a case file.

Creating a new case file

Creating a case file is dead simple:

// Create a new case file object
$myCaseFile = new CaseFile();

// Set the case file title
$myCaseFile->setTitle('My brand new case file');

// Finally, persist the object
CaseFile::persist($myCaseFile);

Sending a case file out for signing

When the case file contains the relevant documents and signers, it has to be "send out for signing" before the signing process can begin. This is accomplished by calling the send() method on the case file object. You can delay the sending by setting the sendAt time using the setSendAt() method on the case file object. This method takes a DateTime object as parameter.

If you want to distribute the signing links yourself, use the activate() method instead to activate the case file signing links.

Once the case file has been sent or activated, documents and signers can no longer be added or removed.

Setting an expiry time on a case file

A case file can be set to expire using the expireAt() method on the object. When a case file is expired, the signers can no longer sign the case file documents. The expireAt() method takes a DateTime object as parameter.

Retrieve existing case files

There is several ways to retrieve case files from Penneo. Available methods for retrieving case files are:

  • CaseFile::find($id) Find one specific case file by its ID.
  • CaseFile::findAll() Find all case files accessible by the authenticated user.
  • CaseFile::findBy(array $criteria, array $orderBy, $limit, $offset) Find all case files matching $criteria ordered by $orderBy. If $limit is set, only $limit results are returned. If $offset is set, the $offset first results are skipped. Criteria can either be title or metaData.
  • CaseFile::findOneBy(array $criteria, array $orderBy) Same as findBy setting $limit = 1 and $offset = null
  • CaseFile::findByTitle($title, array $orderBy, $limit, $offset) Same as findBy using title as criteria.
  • CaseFile::findOneByTitle($title, array $orderBy) Same as findOneBy using title as criteria.
  • CaseFile::findByMetaData($metaData, array $orderBy, $limit, $offset) Same as findBy using metaData as criteria.
  • CaseFile::findOneByMetaData($metaData, array $orderBy) Same as findOneBy using metaData as criteria.

Below is a couple of examples:

// Retrieve all case files
$myCaseFiles = CaseFile:findAll();

// Retrieve a specific case file (by id)
$myCaseFile = CaseFile::find(271184);

// Retrieve all case files that contains the word "the" in their title and sort descending on creation date
$myCaseFiles = CaseFile::findByTitle(
    'the',
    array('created' => 'desc')
);

// Retrieve case files from offset 10 until 110 ordered by title in ascending order
$myCaseFiles = CaseFile::findBy(
	array(),
	array('title' => 'asc'),
	10,
	100
);

Deleting a case file

A case file can be completely deleted from Penneos document store as long as it is in the new state. As soon as it is send out, a delete request will only cause its status to be changed to deleted. A case file is deleted like so:

// Delete case file
CaseFile::delete($myCaseFile);

Retrieving linked objects

A case file contains both signer and document objects. These objects can be retrieved using the following methods:

  • getDocuments() Returns the documents linked to the case file as an array of document objects.
  • getSigners() Returns the signers linked to the case file as an array of signer objects.
  • findSigner($id) Find and return a specific signer by $id.

State variables

A series state variables are used to describe the case file state over the course of its life time. The methods for retrieving the state variables are described below:

  • getStatus() Returns the status of the case file as a string. Possible status values are:
  • new: The case file hasn't been sent out for signing yet
  • pending: The case file is out for signing
  • rejected: One of the signers has rejected to sign
  • deleted: The case file has been out for signing but have since been deleted
  • signed: The case file is signed, but the signed documents are not generated
  • completed: The signing process is completed
  • getCreatedAt() Returns the date and time the case file was created as a DateTime object
  • getSignIteration() Returns the current sign iteration. This is only relevant if the signing process is not parallel. In that case, the signing process is broken into iterations.