TimeSheet.QueueRecallTimesheet Method

Changes the current state of the specified timesheet to be the previous timesheet state, when the current user was the next approver.

Namespace:  [TimeSheet Web service]
Service reference: http://ServerName:32843/[Project Service Application GUID]/PSI/TimeSheet.svc
Web service reference: http://ServerName/ProjectServerName/_vti_bin/PSI/TimeSheet.asmx?wsdl

Syntax

'Declaration
<SoapDocumentMethodAttribute("https://schemas.microsoft.com/office/project/server/webservices/TimeSheet/QueueRecallTimesheet", RequestNamespace := "https://schemas.microsoft.com/office/project/server/webservices/TimeSheet/",  _
    ResponseNamespace := "https://schemas.microsoft.com/office/project/server/webservices/TimeSheet/",  _
    Use := SoapBindingUse.Literal, ParameterStyle := SoapParameterStyle.Wrapped)> _
Public Sub QueueRecallTimesheet ( _
    jobUID As Guid, _
    tsUID As Guid _
)
'Usage
Dim instance As TimeSheet
Dim jobUID As Guid
Dim tsUID As Guid

instance.QueueRecallTimesheet(jobUID, _
    tsUID)

[SoapDocumentMethodAttribute("https://schemas.microsoft.com/office/project/server/webservices/TimeSheet/QueueRecallTimesheet", RequestNamespace = "https://schemas.microsoft.com/office/project/server/webservices/TimeSheet/", 
    ResponseNamespace = "https://schemas.microsoft.com/office/project/server/webservices/TimeSheet/", 
    Use = SoapBindingUse.Literal, ParameterStyle = SoapParameterStyle.Wrapped)]
public void QueueRecallTimesheet(
    Guid jobUID,
    Guid tsUID
)

Parameters

• jobUID
  Type: System.Guid
  The unique ID of the queue job.

• tsUID
  Type: System.Guid
  The unique ID of the timesheet.

Remarks

Timesheets that are approved or that are in the process of being approved cannot be recalled. Surrogates cannot recall a timesheet after it has been submitted.

The QueueRecallTimesheet method is processed asynchronously through the Project Server Timesheet Queue.

This method submits jobs to the QueueSystem object. The CorrelationGUID property for the job is equal to the value of the TS_UID property.

Project Server Permissions

Permission	Description
Non-standard	The current user must be the timesheet owner or manager.

Examples

The following code example determines whether a timesheet exists for the first open period. If it does, the example reads the timesheet. If the timesheet does not exist, the example creates a timesheet with the default timesheet lines that are specified on the server. The example then submits the timesheet and shows the results.

At the end, the sample recalls the timesheet and deletes it so that it can be created again. If you want to view the timesheet approval in Project Web App, comment out the recall and deletion section.

Timesheet periods must be created in the server settings for timesheets to work.

For critical information about running this code sample, see Prerequisites for ASMX-Based Code Samples.

using System;
using System.Collections.Generic;
using System.Text;
using System.Net;
using System.Data;
using System.Threading;
using System.Web.Services.Protocols;
using PSLibrary = Microsoft.Office.Project.Server.Library;

namespace Microsoft.SDK.Project.Samples.QueueSubmitTimesheet
{
   class Program
   {
      [STAThread]
      static void Main()
      {
         try{
            #region Setup
            const string PROJECT_SERVER_URI = "http:// ServerName/ProjectServerName/"; // <<--Change to be the name of your server running Project Server and the name of your directory.
            const string TIMESHEET_SERVICE_PATH = "_vti_bin/psi/timesheet.asmx";
            const string RESOURCE_SERVICE_PATH = "_vti_bin/psi/resource.asmx";
            const string ADMIN_SERVICE_PATH = "_vti_bin/psi/admin.asmx";
            const string QUEUESYSTEM_SERVICE_PATH = "_vti_bin/psi/queuesystem.asmx";
            TimeSheetWebSvc.TimesheetDataSet timeSheetDs;
            Guid jobUid;

            // Set up the services.
            TimeSheetWebSvc.TimeSheet timeSheetSvc = new TimeSheetWebSvc.TimeSheet();
            timeSheetSvc.UseDefaultCredentials = true;
            timeSheetSvc.Url = PROJECT_SERVER_URI + TIMESHEET_SERVICE_PATH;

            ResourceWebSvc.Resource resourceSvc = new ResourceWebSvc.Resource();
            resourceSvc.Url = PROJECT_SERVER_URI + RESOURCE_SERVICE_PATH;
            resourceSvc.UseDefaultCredentials = true;

            AdminWebSvc.Admin adminSvc = new AdminWebSvc.Admin();
            adminSvc.Url = PROJECT_SERVER_URI + ADMIN_SERVICE_PATH;
            adminSvc.UseDefaultCredentials = true;

            QueueSystemWebSvc.QueueSystem q = new QueueSystemWebSvc.QueueSystem();
            q.Url = PROJECT_SERVER_URI + QUEUESYSTEM_SERVICE_PATH;
            q.UseDefaultCredentials = true;

            Guid myUid = resourceSvc.GetCurrentUserUid();
            Guid tsUid;

            #endregion
            #region Read Timesheet
            // Time periods must be created by the admin to use timesheets.
            // We are just reading the first open period here.
            AdminWebSvc.TimePeriodDataSet timeperiodDs = adminSvc.ReadPeriods(AdminWebSvc.PeriodState.Open);
            Guid periodUid = timeperiodDs.TimePeriods[0].WPRD_UID;

            // If timesheet already exists, read it.
            // (To delete an existing unsubmitted timesheet,
            //   go to the My Timesheet area of the PWA site.)
            timeSheetDs = timeSheetSvc.ReadTimesheetByPeriod(myUid,periodUid,TimeSheetWebSvc.Navigation.Current);
            #endregion
            #region CreateTimesheet if it doesn't exist, then read it
            // If the timesheet does not exist, create it.
            if(timeSheetDs.Headers.Count<1)
            {
               timeSheetDs = new TimeSheetWebSvc.TimesheetDataSet();
               TimeSheetWebSvc.TimesheetDataSet.HeadersRow headersRow = timeSheetDs.Headers.NewHeadersRow();
               headersRow.RES_UID = myUid;
               headersRow.TS_UID = Guid.NewGuid();
               headersRow.WPRD_UID = periodUid;
               headersRow.TS_CREATOR_RES_UID = myUid;
               headersRow.TS_NAME = "Timesheet ";
               headersRow.TS_COMMENTS = "Random comment text here";
               headersRow.TS_ENTRY_MODE_ENUM = (byte)PSLibrary.TimesheetEnum.EntryMode.Weekly; 
               timeSheetDs.Headers.AddHeadersRow(headersRow);

               // Create the timesheet with the default line types that are specified by the admin.
               timeSheetSvc.CreateTimesheet(timeSheetDs, TimeSheetWebSvc.PreloadType.Default);
               timeSheetDs = timeSheetSvc.ReadTimesheet(headersRow.TS_UID);
            }
            CodeSampleUtilities.WriteTablesFormated("Timesheet after create:" ,timeSheetDs.Tables);
            tsUid=timeSheetDs.Headers[0].TS_UID;
            #endregion
            #region Submit timesheet, if the status is OK
            if ((timeSheetDs.Headers[0].TS_STATUS_ENUM != (byte)PSLibrary.TimesheetEnum.Status.Approved)
               && timeSheetDs.Headers[0].TS_STATUS_ENUM != (byte)PSLibrary.TimesheetEnum.Status.Submitted
               )
            {
               jobUid = Guid.NewGuid();
               timeSheetSvc.QueueSubmitTimesheet(jobUid,tsUid,myUid,"I created this timesheet and submitted it through my handy-dandy program.");
               CodeSampleUtilities.WaitForQueue(q, jobUid);
            }
            timeSheetDs = timeSheetSvc.ReadTimesheet(tsUid);
            CodeSampleUtilities.WriteTablesFormated("After submission:", timeSheetDs.Tables);
            #endregion
            #region Recall the timesheet and delete it
            // Recall the timesheet and delete it so that we can run the sample again.
            jobUid = Guid.NewGuid();
            timeSheetSvc.QueueRecallTimesheet(jobUid,tsUid);
            CodeSampleUtilities.WaitForQueue(q, jobUid);

            jobUid = Guid.NewGuid();
            timeSheetSvc.QueueDeleteTimesheet(jobUid, tsUid);
            CodeSampleUtilities.WaitForQueue(q, jobUid);
            #endregion
         }
         #region Exception Handlers
         catch (SoapException ex)
         {
            ExceptionHandlers.HandleSoapException(ex);
         }
         catch (WebException ex)
         {
            ExceptionHandlers.HandleWebException(ex);
         }
         catch (Exception ex)
         {
            ExceptionHandlers.HandleException(ex);
         }
         finally
         {
            ExceptionHandlers.ResetConsole();
         }
         #endregion
      }
      class ExceptionHandlers
      {

         public static void HandleSoapException(SoapException ex)
         {
            PSLibrary.PSClientError error = new PSLibrary.PSClientError(ex);
            PSLibrary.PSErrorInfo[] errors = error.GetAllErrors();
            string errMess = "==============================\r\nError: \r\n";
            for (int i = 0; i < errors.Length; i++)
            {
               errMess += "\n" + ex.Message.ToString() + "\r\n";
               errMess += "".PadRight(30, '=') + "\r\nPSCLientError Output:\r\n \r\n";
               errMess += errors[i].ErrId.ToString() + "\n";

               for (int j = 0; j < errors[i].ErrorAttributes.Length; j++)
               {
                  errMess += "\r\n\t" + errors[i].ErrorAttributeNames()[j] + ": "
                     + errors[i].ErrorAttributes[j];
               }
               errMess += "\r\n".PadRight(30, '=');
            }
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine(errMess);
         }

         public static void HandleWebException(WebException ex)
         {
            string errMess = ex.Message.ToString() +
               "\n\nLog on, or check the Project Server Queuing Service";
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine("Error: " + errMess);
         }

         public static void HandleException(Exception ex)
         {
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine("Error: " + ex.Message);
         }

         public static void ResetConsole()
         {
            Console.ResetColor();
            Console.WriteLine("\r\n\r\nPress any key...");
            Console.ReadKey();
         }
      }
      class CodeSampleUtilities
      {
         // Write all contents of a table collection to the console.
         public static void WriteTablesToConsole(System.Data.DataTableCollection theTables)
         {
            Console.ForegroundColor = ConsoleColor.DarkGreen;
            foreach (System.Data.DataTable table in theTables)
            {

               int[] columnWidths = new int[table.Columns.Count];
               int tableWidth = 0;
               string dataString;
               Console.WriteLine("Table: " + table.TableName);

               // Write out the column names and get their spacing.
               StringBuilder tableRow = new StringBuilder();
               for (int i = 0; i < table.Columns.Count; i++)
               {
                  columnWidths[i] = GetColumnWidth(table.Columns[i]);
                  tableRow.Append(table.Columns[i].ColumnName.PadRight(columnWidths[i]));

                  tableWidth += columnWidths[i];
               }
               // Add a space so that it will not wrap.
               tableWidth += 1;
               // Make the console as wide as the widest table.
               Console.BufferWidth = (Console.BufferWidth > tableWidth ? Console.BufferWidth : tableWidth);
               tableRow.Append("\r\n");
               Console.Write(tableRow.ToString());

               // Write out the data.
               foreach (DataRow row in table.Rows)
               {
                  tableRow = new StringBuilder();
                  for (int i = 0; i < table.Columns.Count; i++)
                  {

                     dataString = row[i].ToString();
                     // Truncate output if it is wider than 
                     // the desired column width.
                     if (dataString.Length >= columnWidths[i])
                     {
                        dataString = dataString.Substring(0, columnWidths[i] - 1);
                     }
                     // Add the output to the stringbuilder and pad right to fill
                     // up to the column width.
                     tableRow.Append(dataString.PadRight(columnWidths[i]));
                  }
                  tableRow.Append("\r\n");
                  Console.Write(tableRow.ToString());
               }
               Console.Write("\r\n".PadLeft(tableWidth, '-'));
            }
            Console.ResetColor();
         }
         // A helper function for WriteTablesToConsole.
         private static int GetColumnWidth(DataColumn column)
         {
            // Note: Might not handle byte[]data types well.
            const int MAX_COL_WIDTH = 40;
            int dataWidth = 0;

            // Return 12 for numbers, 30 for dates, and string width for strings.
            switch (column.DataType.UnderlyingSystemType.ToString())
            {
               case "System.Boolean":
               case "System.Byte":
               case "System.Byte[]":
               case "System.Char":
               case "System.Decimal":
               case "System.Double":
               case "System.Int16":
               case "System.Int32":
               case "System.Int64":
               case "System.SByte":
               case "System.Single":
               case "System.UInt16":
               case "System.UInt32":
               case "System.UInt64":
                  dataWidth = 12;
                  break;
               case "System.DateTime":
               case "System.TimeSpan":
                  dataWidth = 30;
                  break;
               case "System.Guid":
                  dataWidth = 37;
                  break;
               case "System.String":
                  // If it has a maxlength, use it.
                  if (column.MaxLength > 0)
                  {
                     dataWidth = column.MaxLength;
                  }
                  else
                  {
                     // Otherwise, use the max col width.
                     dataWidth = MAX_COL_WIDTH;
                  }
                  break;
               default:
                  dataWidth = column.ColumnName.Length;
                  break;
            }
            // Truncate if over the maxlength.
            if (dataWidth > MAX_COL_WIDTH)
            {
               dataWidth = MAX_COL_WIDTH;
            }
            // Always be at least as wide as the colum name.
            return (column.ColumnName.Length > (dataWidth) ? column.ColumnName.Length + 1 : dataWidth);
         }
         public static void WriteTablesFormated(string Title, System.Data.DataTableCollection theTables)
         {
            WriteSeparator();

            Console.WriteLine(Title);

            CodeSampleUtilities.WriteTablesToConsole(theTables);

         }
         public static void WriteSeparator()
         {
            Console.ForegroundColor = ConsoleColor.DarkYellow;
            Console.WriteLine("".PadRight(Console.BufferWidth, '='));
            Console.ResetColor();

         }

         // Wait for the job to finish.
         // Outputs job status to the console.
         static public void WaitForQueue(QueueSystemWebSvc.QueueSystem q, Guid jobId)
         {
            QueueSystemWebSvc.JobState jobState;
            const int QUEUE_WAIT_TIME = 1; // One second
            bool jobDone = false;
            string xmlError = string.Empty;
            int wait = 0;

            //Wait for the project to get through the queue.
            // Get the estimated wait time in seconds.
            wait = q.GetJobWaitTime(jobId);

            // Wait for it.
            Console.Write("Waiting on queue. Estimate: {0} seconds.\r\n ", wait);

            // Wait until it is finished.

            do
            {
               // Get the job state.
               jobState = q.GetJobCompletionState(jobId, out xmlError);

               if (jobState == QueueSystemWebSvc.JobState.Success)
               {
                  jobDone = true;
               }
               else
               {
                  if (jobState == QueueSystemWebSvc.JobState.Unknown
                  || jobState == QueueSystemWebSvc.JobState.Failed
                  || jobState == QueueSystemWebSvc.JobState.FailedNotBlocking
                  || jobState == QueueSystemWebSvc.JobState.CorrelationBlocked
                  || jobState == QueueSystemWebSvc.JobState.Canceled)
                  {
                     // If the job failed, error out.
                     throw (new ApplicationException("Queue request " + jobState + " for Job ID " + jobId + ".\r\n" + xmlError));
                  }
                  else
                  {
                     //Console.WriteLine("Job State: " + jobState + " for Job ID: " + jobId);
                     Console.Write("~");
                     Thread.Sleep(QUEUE_WAIT_TIME * 1000);
                  }
               }
            }
            while (!jobDone);
            Console.Write("\r\n");
         }
      }
   }
}

See Also

Reference

TimeSheet Class

TimeSheet Members

TimeSheet Web Service